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Preface 


Controlling Document 


Audience 


This document describes SunCore, an implementation of the ACM SIGGRAPH 
Core System by Sun Microsystems, Inc. SunCore conforms to level 3C (dynamic 
output with 3D scaling, rotation and translation) of the Core specification for out¬ 
put primitives, and to level 2 (complete input) for input primitives. Appendix A 
summarizes the differences between SunCore and ACM SIGGRAPH Core System. 

The following document was used in interpreting the ACM SIGGRAPH Core Sys¬ 
tem: 

[1] Status Report of the Graphics Standards Planning Committee. Computer 
Graphics. Volume 13, Number 3, August 1979. 

The intended reader of this document is an applications programmer who is fami¬ 
liar with interactive computer graphics and the C programming language. This 
manual contains several example programs that can be used as templates for 
larger SunCore applications. 
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Introduction 


SunCore is a comprehensive package of engineering graphics software providing 
the underlying support for interactive graphics applications programs. It is based 
on the ACM Core System, a graphics standard designed for 3D interactive graph¬ 
ics. 

SunCore provides extensions to the ACM Core System. These include textured 
polygon fill algorithms, raster primitives, RasterOp attributes, shaded surface 
polygon rendering, and hidden surface elimination. 

SunCore supports both the high resolution monochrome bitmap displays and the 
Sun color displays. Device-dependent functions support all these displays under 
SunCore. SunCore can also be used in conjunction with the Sun Graidiics Pro¬ 
cessor and Graphics Buffer options. 

Note that this manual is a reference manual for the SunCore graphics package. It 
is not a tutorial for the programmer without knowledge of graphics principles. It 
assumes that the reader is familiar with the concepts of graphics, and has some 
familiarity with the ACM Core specification. Those who are new to graphics 
should consult one of the publications listed in Section 1.7. 

1.1. Where to Start If you are an applications programmer who is familiar with the ACM Core 

specification, but are new to SunCore, it is recommended that you read Appendix 
A in order to become familiar with the areas where SunCore deviates from and 
provides extensions to the ACM Core specification. 

Note that SunCore supports the ACM Core output level 3C, that is, dynamic out¬ 
put is supported, including 2 and 3D translation, scaling and rotation. SunCore 
supports the ACM Core input level 2, that is, synchronous input, including the 
PICK device. SunCore supports dimension level 2, that is, 3D operations. 

1.2. Overview and The objective of a graphics application program is drawing pictures and text on 

Terminology some display device, be it an e^diemeral display device such as TV monitor or 

terminal, or a hard copy device such as a plotter or printer. 

There is a need for a device-independent way of representing graphics images in 
the computer, and having a collection of software functions map the device¬ 
independent representations into the physical representations that the output dev¬ 
ice can handle. SunCore is an implementation of one of the “standard” pack¬ 
ages of graphics software that have appeared recently. This section introduces 
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some of the terminology of SunCore. This terminology is used throughout this 
manual. It is somewhat easier to describe the terminology from the point of view 
of the physical device woridng backwards to the application program, rather than 
starting at the software and working out to the device. 

There are two quite distinct points of view for looking at a system running a 
graiMcs application: 

o The physical device (monitor^ printer, and so on) on which the final pictures 
appear, and 

□ The internal world which the programmer uses to describe the pictures, and 
which (because of SunCore) is independent of the physical device. 

A view surface v& a physical surface on which the final picture appears. 

There are two interdependent sets of coordinate systems in use in the graphics 
package: 

World Coordinates 

is a coordinate system which is device-independent. The applications pro¬ 
grammer constructs all graphical objects in terms of world coordinates. 

Normalized Device Coordinates 

(often abbreviated as NDC) is a fixed coordinate system which is indepen¬ 
dent of physical output devices. World coordinates are transformed to NDC 
space for clipping and other operations. Each physical output device driver 
then transforms from NDC space to the physical device coordinates for each 
view surface. 

A viewport s a region of NDC space which the programmer selects and on which 
the pictures will appear. 

It is the job of the viewing transformations to perform the correct mapping 
between world coordinates and NDC space. 

A window is a region defined in world coordinates within which the images that 
the application program defines ^pear. The selection of the coordinates for the 
window are arbitrary — the graphics package maps the window into the 
viewport. 

In 3D, the transformation from the window to the viewport is a relatively 
straightforward process. In 3D, another level of complexity is introduced with 
the notion of a view plane which is positioned arbitrarily in world coordinates. 

An output primitive, or often just a primitive, is a part of a picture (such as a line 
or a character string). The appearance of primitives (such as solid or dotted 
lines) is determined by primitive attributes. A primitive attribute is a general 
characteristic'of an output primitive, and affects the appearance of that primitive. 
Examples of primitive attributes are color, linestyle, and linewidth. 

Each output primitive may be assigned a name, called the pick-id, which is used 
to identify that primitive when an input operation (such as pointing at the primi¬ 
tive with the mouse) is applied. 
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The current position is a SunCore system value that defines the current location 
for drawing. At startup time, the current position is set to die origin of the world 
coordinate system. Functions that create output primitives (move, line, and so 
on) can alter the current position. 

Output primitives are collected together in segments. A segment defines an 
image which is a part of the picture on a view surface. 

Segments are divided into two classes, namely: temporary and retained. A 
retained segment has a name, and can have segment attributes associated with it. 
A temporary segment is nameless, and furthermore, the image diat a temporary 
segment defines only remains visible as long as information is ordy being added 
to the view surface. As soon as a new frame action (one which repaints view sur¬ 
face) occurs, the temporary segment’s image disappears from the view surface. 

Each retained segment has one static attribute, its image transformation type. 

The value of this attribute can be none, translatable , or tran^ormable. 
Translatable and transformable retained segments can be translated or 
transformed in either 2 or 3D. 

Segments also have dynamic attributes. The visibility and highlighting attributes 
control the appearance of the image. The detectability attribute determines if the 
segment can be detected by the pick device. Dynamic attributes for translatable 
and transformable segments include the segment’s image transformation. 
Depending on the image transformation type, the image transformation may con¬ 
tain translation, rotation, and scaling components. 

A viewing operation is an operation that maps positions in world coordinates to 
positions in NDC space. The viewing operation also determines the portion of 
the world coordinate space that is visible if window clipping or depth clipping is 
enabled. 

The applications program can obtain user interaction by means of input primi¬ 
tives, wtuch provide facilities for pointing at objects, entering data ftom the key¬ 
board, and causing events. 

Basics of Drawing Pictures The general sequence of actions that an application program goes through to 

create a picture on a device is this; 

1 . Initialize SunCore. 

2. Initialize a view surface upon which the picture will be drawn. 

3. Select a view surface upon which the picture will be drawn. 

4. Specify the viewing operation parameters (sizes of windows in world coordi¬ 
nates, size of viewport, and so on). 

5. Set an image transformation type. 

6 . Create a segment. The created segment becomes the currently open segment 
until it is closed. 

7. Set attributes for the segment, if required. 
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8 . Draw objects in the segment using output primitives. 

9. Close the segment. 

10. Repeat steps 4 through 9 as often as required, for as many segments as 
needed to build the picture. 

11. Apply image transformations (translation, scaling, and rotation) to a given 
segment, to achieve the required picture on the display device. 

12. Deselect the view surface. 

13. Terminate SunCore. 


In providing the application programmer with the capabilities needed to draw 
pictures, SunCore breaks the interface into six functional areas: 

Control 

directs the major actions of SunCore, such as startup, shutdown, selection 
and deselection of view surfaces, and so on. 

Segments 

control the creation, closing, and removal of segments. Segments are then 
used to collect sets of: 


Output Functions 

also known as output primitives, which describe the drawing of lines and 
line sequences, shaded regions, text, and markets. 

Attributes 

control the way in which output primitives actually appear in the final image 
(solid or dotted lines, for instance). 



Transformations 

control the major appearances of pictures, such as orientation (rotation), 
scaling, and translation. Transformations also control projection type and 
clipping. 

Input Functions 

handle the interaction with die user via the keyboard and the mouse. 


This section provides an example of a SunCore application program. The 
glass. c program draws a martini glass on the screen. This program demon¬ 
strates the use of: 

□ Creating a temporary segment (see Segmentation and Naming), 
o Moving to an absolute position (see Output Primitives), 

o Using the polyline drawing functions (see Output Primitives), 

□ Using the absolute line drawing functions (see Output Primitives), 
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tinclude <usercore.h> 

static float glassdx[] = { -10 -0,r 9.0, 0.0,-14.0,30.0, 

-14.0,0.0,9.0,-10.0 }; 

static float glassdy[] - { 0.0,1.0,19.0,15.0,0.0, 

-15.0,-19.0,-1.0,0.0 }; 

int pixwindd(); 

struct vwsurf vwsurf = DEFAULT_VWSURF(pixwindd); 

mainO 

{ 

initialize_core (BASIC, NOINPUT, TWOD); 
initialize_view_surface(&vwsurf, FALSE); 
select_view_surface(&vwsurf); 
set__viewport_2 (0.125, 0.875, 0.125, 0.75) ; 
set_window(-50.0, 50.0, -10.0, 80.0); 

create__temporary_segment () ; 
move_abs_2 (0.0, 0.0); 
polyline_rel_2 (glassdx, glassdy, 9) ; 
move_rel_2 (-12.0, 33.0); 
line_rel_2 (24.0, 0.0); 
close_temporary_segment(); 

sleep(10); 

deselect__view__surface (&vwsurf) ; 
terminate coreO; 


Figure 1-1 Simple Example Program 

glass. c can be compiled with the following command line: 

cc glass.c -fswitch -o glass -Icore -Isunwindow —Ipixrect —Im 

In the command line above, the options: 


—fswitch 


“Icore 


causes the compiler to take advantage of floating point 
hardware if it is available. Otherwise, the compiler will emu¬ 
late this floating point support with software. (For more infor¬ 
mation on floating point options, see Appendix F). 

selects die SunCore run-time library from 
/usr/lib/libcore.a. 


—Isunwindow selects the window system library, 
—Ipixrect selects the pixrect library, 

—Im selects the correct math library. 


rTwrosystems 
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1.4. The SunCore Lint 
Library 


1.5. The Coordinate 
Systems 


I 


i 



When the compilation is complete, the final program is in the file glass and 
may be run by typing its name. 

This example uses the some but not all of SunCore's capabilities. Appendix I 
contains an example that illustrates other areas of the SunCore graphics package. 




SunCore provides a lint (1) library which provides type checking beyond the 
capabilities of the C compiler. For example, you could use the SunCore 
lint (1) library to check a program called glas s. c with command like this: 



Note that the error messages that lint (1) generates are mostly warnings, and 
may not necessarily have any effect on the operation of the program. For a 
detailed explanation of lint (1), see the lint (1) chapter in the Program¬ 
ming Tools manual. 


Applications programs which draw pictures using SunCore communicate in 
world coordinates. World coordinates are a device-independent, 2 or 3D, Carte¬ 
sian coordinate system for describing objects. Output primitives are given to 
SunCore functions in World Coordinates (WC). However, if the world coordi¬ 
nate matrix is used, SunCore concatenates this matrix with the view transform so 
that output primitives are first transfonned by this matrix from ‘model’ or 
‘object’ coordinates to world coordinates. This means that the user can supply 
primitives in ‘model’ coordinates, each model or object being moved into world 
coordinates according to the current world coordinate matrix. 


In 3D, the user may choose to use right-handed or left-handed world coordinates. 
In a right-handed system, if (for example) the x coordinate increases to the tight 
and the y coordinate increases upwards, then the z coordinate increases towards 
the viewer. In the corresponding left-handed system, the x coordinate increases 
to the right, the y coordinate increases upwards, and the z coordinate increases 
away from the viewer. 


The composite viewing transform is formed from the world coordinate matrix 
and the viewing parameters. SunCore functions transform the output primitives 
from world (or model) coordinates to NDC, which is a left-hand coordinate sys¬ 
tem bounded such that: 0.0^ ,y ,z <1.0 

Since current Sun view surfaces have four-to-three aspect ratios, the default NDC 
space has the y extent bounded to 0.0<y <0.75. Primitives are stored in the 
Display List (also called the Pseudo Display File or PDF), in NDC space. The 
user-specified window in worid coordinates is mapped (and optionally clipped) 
to the user-specified viewport within NDC space. The entire NDC space is then 
mapped to the selected physical view surfaces. 
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1.6. Details of Using 
SunCore 


This section describes the details of creating applications programs to mn with 
SunCore. 


Classification of Functional 
Capabilities 


The ACM Core specification defines levels of functional capability for a graphics 
package which implements the specification. The table below shows the 
classification. Terms such as BUFFERED and DYNAMICA are defined as con¬ 
stants in the file <usercore. h>, discussed below. 


Table 1-1 Output Capabilities 


Functional Capability 

BASIC 

BUFFERED 

DYNAMICA 

DYNAMICB 

DYNAMICC 

Output Primitives and 
Primitive Attributes. 

yes 

yes 

yes 

yes 

yes 

Viewing 

yes 

yes 

yes 

yes 

yes 

Control 

yes 

yes 

yes 

yes 

yes 

Temporary Segments 

yes 

yes 

yes 

yes 

yes 

Retained Segments 

no 

yes 

yes 

yes 

yes 

Highlighting Segment 
Attribute 

no 

yes 

yes 

yes 

yes 

Visibility Segment 
Attribute 

no 

yes 

yes 

yes 

■yes 

Image Transformation 
Segment Attribute 

no 

no 

yes 

yes 

yes 

Detectability Segment 
Attribute 

no 

* 

yes 

♦ 

yes 

* 

yes 

* 

yes 


* This feature is only available if input levels SYNCHRONOUS or COMPLETE 
are supported. Note that SunCore supports all output levels up to DYNAMICC. 


Table 1-2 Input Capabilities 


Functional Capability 

NOINPUT 

SYNCHRONOUS 

COMPLETE 

Device Initialization and Termination 

no 

yes 

yes 

Synchronous Interaction Functions 

no 

yes 

yes 

Echo Control 

no 

yes 

yes 

Explicit Enable or Disable 

no 

no 

yes 

Event Queue Management 

no 

no 

yes 

Sampled Device Functions 

no 

no 

yes 

Associations 

no 

no 

yes 


Note that SunCore supports up to the SYNCHRONOUS input level. 


msun 

Xr microsystems 


Revision A, of 9 May 1988 






10 SunCore Reference Manual 


Table 1-3 Dimension Levels Supported 


Functional Capability 

TWOD 

THREED 

2D Primitives, 

Attributes, and Viewing. 

yes 

yes 

3D Primitives, 

Attributes, and Viewing. 

no 

yes 


Note that SunCore supports up to the THREED dimension level. 

Error Reporting SunCore performs consistency checks on arguments passed to its various func¬ 

tions. Any time an error is detected, the name of the function which raised the 
error condition and the text of the error message ate printed on the standard error 
(stderr). 

All SunCore interfaces axt functions that return a value. If a function completes 
successfully, it returns the value zero. If the function raises any error conditions, 
it returns a non-zero value. SunCore always identifies the name of the function 
which raised the error condition. The ACM Core specification defines specific 
error numbers. These do not correspond to SunCore’s error numbers in the 
current release. 

Useful Constants in the The file <usercore. h> defines a collection of constants which the application 

<user core . h> Include File programmer should use in lieu of hardwired constants in code. The constants are 

described here (but their values are not stated). 

Useful Constants: 

TRUE A universal value denoting the truth value. 

FALSE A universal value denoting the false value. 

MAXVSURF The maximum number of view surfaces which may be initialized 
at any one time. 

Initialization Constants. These constants describe the levels of the SunCore 
facilities which the application program will use. These constants should be used 
when calling the init ialize_core () function. 

BASIC Denotes the basic output level. See the tables above for the 
classifications. 

BUFFERED 

Denotes the buffered output level. See the tables above for the 
classifications. 

DYNAMICA 

Indicates that the application package wishes to use 2D translation 
facilities. See the tables above for the classifications. 

DYNAMICB 

Indicates that the application package wishes to use 3D scaling, rota¬ 
tion, and translation facilities. See the tables above for the 
classifications. 
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DYNAMICC 

Indicates that the application package wishes to use 3D scaling, rota¬ 
tion, and translation facilities. See the tables above for the 
classifications. 

NOINPUT Indicates that this application package will not use any input facili¬ 
ties. See the tables above for the classifications. 

SYNCHRONOUS 

Indicates that this application program will use synchronous input 
facilities. See the tables above for the classifications. 

COMPLETE 

SunCore does not support (his input level. See (he tables above for 
the classifications. 

TWOD Indicates that the application package will only use 2D functions. 

See the tables above for the classifications. 

THREED Indicates that the application package will use both 2D and 3D func¬ 
tions. See the tables above for (he classifications. 


Character Quality Constants. These constants should be used when calling the 
set_charprecision 0 function. 

STRING Denotes low quality text. 

CHARACTER 

Denotes medium quality text 

Transform Constants. These constants should be used when calling the 
set_pro jection 0 and set_coordinate_system_tYpe () functions. 

PARALLEL 

Value to indicate parallel projection. 


PERSPECTIVE 

Value to indicate perspective projection. 

RIGHT Value to indicate right-handed world coordinate system. 

LEFT Value to indicate left-handed world coordinate system. 

Image Tranrformation Type Constants. These constants are used when calling 
the set_image_trans formation_type () and 
set_segment_image_transformation_type () functions. 

NONE Indicates a retained segment which carmot be transformed. 

XLATE2 Indicates a retained segment which may be translated in 2D. 

XFORM2 Indicates a retained segment which may be fully translated, scaled, 
and rotated, in 2D. 

XLATE3 Indicates a retained segment which may be translated in 3D. 

XFORM3 Indicates a retained segment which may be fully translated, scaled, 
and rotated, in 3D. 
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Line Style Constants. These constants should be used when calling the 

set_linestyle() attribute for output primitives. 

SOLID Solid line. 

DOTTED Dotted line. 

DASHED Dashed line. 

DOTDASHED 

Dashed apd dotted line. 

Text Font Selection Constants. These constants should be used when calling 

set_font(). 

ROMAN For character precision, a Roman font; for string precision, a raster 
font. 

GREEK For character precision, a Greek font; for string precision, the 

default raster font. 

SCRIPT For character precision, a Serij«; font; for string precision, a small 

raster font. 


OLDENGLISH 

For character precision, an Old English font; for string precision, 
equivalent to ROMAN. 

STICK This is equivalent to a medium sized ROMAN raster font. 

SYMBOLS This is equivalent to a bold version of STICK. It currently holds 
some electronics symbols (character values 32 through 47). 

Input Device Constants. These constants should be used when calling the 
initialize_device () and terminate_device () functions and other 
input functions. 

PICK The Picit device. The mouse in SunCore. 

KEYBOARD 

ThQ Keyboard d&vice. 

STROKE The freehand STROKE device. The mouse in SunCore. 

LOCATOR The locator device. The mouse in SunCore. 

VALUATOR 

The Valuator device. The mouse in SunCore. 

BUTTON The Button device. The mouse in SunCore. 


RasterOp Constants. These constants should be used when calling the 
set_rasterop () function. 

NORMAL Indicates normal copy mode. 

XORROP Indicates bitwise exclusive or of source and destination. 
ORROP Indicates bitwise or of source and destination. 


o 
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1.7. Further Reading 



s 


Polygon Rendering Style Constants. These constants should be used when cal¬ 
ling the set_j>olygon_interior_stYle () and 
set_shading_parameters 0 functions. 

PLAIN Indicates area fill with the color indicated by the fill index primitive 
attribute. 

SHADED Indicates shading according to the current shading parameters (for 
3-D polygons only). 

CONSTANT 

Indicates constant user-specified shade. 

GOURAUD 

Indicates Gouraud shading. 

PHONG Indicates Phong shading. 

[1] Conrac Corporation. Raster Graphics Handbook, Second Edition. Van 
Nostrand Reinhold, 1985. 

[2] J.D. Foley and A. Van Dam. Fundamentals of Interactive Computer 
Graphics. Addison-Wesley, 1982. 

[3] W.M. Newman and R.F. Sproull. Principles of Interactive Computer 
Graphics. McGraw-Hill, 1979. 

[4] ACM-SIGGRAPH. Conference Proceedings. 

[5] IEEE Computer Graphics and Applications. 

[6] Status Report of the Graphics Standards Planning Committee. Computer 
Graphics. Volume 13, Number 3, August 1979. 

[7] Special Issue on Graphics Standards. ACM Computing Surveys. Volume 
10, #4, December 1978. 

[8] The SIGGRAPH Core System Today. Computer Graphics World. Volume 
5, #8, August 1982. 

[9] SunView Programmer’s Guide. Sun Microsystems. 

[10] SunView System Programmer’s Guide. Sun Microsystems. 

[11] Pixrect Reference Manual. Sun Microsystems. 

[12] SunCGI Reference Manual. Sun Microsystems. 

[13] FORTRAN Programmer’s Guide for the Sun Workstation. Sun Microsys¬ 
tems. 

[14] Pascal Programmer’s Guide for the Sun Workstation. Sun Microsystems. 
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Control 


The SunCore graphics package provides several functions for controlling the sys¬ 
tem. These functions are discussed here, and the sections and subsections which 
follow describe the individual functions in detail. 

Initialization and termination 

of SunCore provide for the initialization of the package to a specific and 
predetermined state, and for closing it down when the applications program 
has finished using the graphics package. 

View surface control 

provides for the initialization, termination, and selection of view surfaces. A 
view surface must be initialized before it can be used. A view surface 
should be terminated when die applications package has finished with it. 
Functions are provided to add view surfaces to the set of selected view sur¬ 
faces, and to remove view surfaces from that set. View surface names in 
SunCore are stmctures. The vwsurf structure is declared in 
<usercore. h> and is described in Appendix B. SunCore supports 
several view surfaces; see Appendix B for details of view surfaces. 

Picture change control 

provides for the “batching” of changes to dynamic segment attributes so 
that the application program may force the simultaneous occurrence of a 
group of changes. 

Frame control 

denotes the function called new_f rame (), which clears the view surface 
and redraws all segments except temporary segments. 

Error handling 

is that part of SunCore concerned witii reporting errors to the application 
program. 

2.1. Initialization and There are two functions provided for initializing and termin atin g SunCore. The 

Termination application program should call initialize_core () before making any 

other calls upon the graphics system. terminate_core () should be the last 
call to SunCore before the application program itself is finished. 
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Initialize the SunCore System initialize_core (output_level, input_level, dimension) 

int output_level; /* SunCore Level for Output */ 

/* BASIC, BUFFERED, DYNAMICA */ 

/* DYNAMICB, DYNAMICC */ 

int input_level; /* SunCore Level for Input */ 

/* NOINPUT, SYNCHRONOUS, COMPLETE */ 
int dimension; /* Number of Dimensions Required */ 

/* TWOD, THREED */ 

init ialize_core () initializes the Core graphics package to a known state. 

SunCore supports up to output level DYNAMICC of the ACM Core specification, 
up to input level SYNCHRONOUS of the ACM Core, and dimension level 
THREED of the ACM Core. 

o The SunCore system is already initialized. 

□ The specified output level cannot be supported, 
o The specified input level cannot be supported. 

□ The specified dimension cannot be supported. 


Close Dovm the SunCore 
System 

2.2. Initializing and 
Selecting View 
Surfaces 


Initialize a View Surface 


terminate core() 


terminate_core () closes down the Core graphics package. 

View surface control provides for the initialization, termination, and selection of 
view surfaces. A view surface must be initialized before it can be used. A view 
surface should be terminated when the applications package has finished with it 
Examples of view surfaces are the Sun color display and the Sun monochrome 
bitmap display. Functions provided in this category are: 



initial!ze_view_surface 

performs the functions required to gain access to a specified view surface. 

terminate_view_surface 

terminates access to the specified view surface. 

select_view_surface 

adds the specified view surface to the set of selected view surfaces for out¬ 
put 


deselect_view_surface 

removes the specified view surface from the set of selected view surfaces. 

inquire_selected_surfaces 

determines which view surfaces are currently selected (not yet imple¬ 
mented). 


initialize_view_surface(surface_name, type) 
struct vwsurf *surface_name; /* See Appendix B */ 

int type; /* TRUE for hidden surface removal, f 

FALSE otherwise */ 
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initialize_view_surf ace () initializes the Core package for a specific 
view surface. 

The surf ace_name argument to the function specifies a physical view surface. 
View surface names in SunCore are structures. The structure is defined in 

the <usercore. h> header file. Only color or gray scale devices support 
hidden-surface removal. 

□ The view surface specified by surface_ncime is already initialized. 

n The view surface specified by surf ace_name does not have any output dev¬ 
ice associated with it. 

□ No other view surfaces can be initialized at this time. 

□ The specified view surface does not support hidden surface removal. 


Close Down a View Surface tenninate_view_surface (surf ace_name) 

struct vwsurf *surface_nanie; /* See Appendix B */ 

terminate_view_surf ace () closes down the specified view surface. 

o The view surface specified by surf ace_name is not initialized. 

Add View Surface to Selected select_view_surface(surface_naine) 

Set struct vwsurf *surface_narae; /* See Appendix B */ 

select_view_surf ace () adds a specified view surface to the list of 
selected view surfaces. 

A segment is only drawn on those view surfaces marked as ‘ ‘selected’ ’ at the 
time that the segment is created. 

□ A segment is open. 

□ The view surface specified by surf ace_name is not initialized. 

□ The view surface specified by surf ace_name is already selected. 

□ The view surface specified by surface_name caimot be selected. 


Remove View Surface from 
Selected Set 


deselect_view_surface (surface_nan»e) 

struct vwsurf *surface_name; /* See Appendix B */ 

deselect_view_surf ace () removes a specified view surface from the list 
of selected view surfaces. 

Segments created after deselect_view_surf ace () is called will not be 
drawn on the deselected view surface. 

□ A segment is open. 

□ The view surface specified by surf ace_name is not selected. 
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2.3. Batching of Updates 


Indicate Start of a Batch of 
Updates 


SunCore provides the facility for the application program to indicate that a 
sequence of updates is being started, and the graphics package stacks up these 
picture changes until an end._batch_of_updates () function call indicates 
that the end of the sequence of updates has occurred. Picture changes or 
‘updates’ include dynamic segment attributes such as visibility, detectability, 
translate, rotate, and scale. 




begin_batch_of_updates() 

begin_batch_of_updates () indicates the beginning of a batch of updates 
to the picture. All modifications to dynamic attributes of segments between calls 
to begin_batch_of_updates () and end_batch_of_updates () are 
saved up and executed simultaneously. 

□ There has been no end_batch_of_updates () function call since the last 
begin_batch_of_updates () function call. 


Indicate End of a Batch of 
Updates 


Start New Frame Action for 
Selected View Surfaces 


end_batch_of_updates() 

end_batch_of_updates () indicates the end of a batch of updates. The 
batch of changes to dynamic attributes of segments is executed, 

□ There has been no corresponding begin_bat ch_of_updates () function 
call. 


new_frame() 

new_f rame () starts new frame action for currently selected view surfaces. 
The view surface is cleared, and all visible retained segments are redrawn. 

□ The set of currently selected view surfaces is empty. 



2.4. Error Control 


The following functions control the display of error information. This informa¬ 
tion can be used to determine the source of an error. 


Report Most Recent Error report_most_recent_error {error_nuniber) 

int *error_nuinber; 

report_most_recent_error () obtains a copy of the most recently 
detected error number. A value of zero returned to error_nuinber indicates 
that there has been no error since the last call on 
report_most_recent_error(). 


Print Error print_error("Your message", error_number); 

int error_number; 

print_error () prints the message associated with this error_number on 
the standard error file (stderr). Your message is any character string that the user 
wants printed. The error message is printed on the line following “Your mes¬ 
sage” 

O’ 
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2.5. Miscellaneous 

Drag Control (SunCore 
Extension) 


Signal Handling 


The following functiotu provide extensions to the Core System. 
set_drag(mode) 

int mode; /* FALSE = uses the rasterop */ 

/* set by set_rasterop */ 

/* TRUE = enable XOR'ing */ 

set_drag () writes all output to the bitmap or color framebuffer with XOR- 
ing. If dragging is enabled, all output to the device drivers is done with XOR’s to 
the data in the displays. This feature makes dragging more convenient For 
example, if you want to drag segment A across segment B, leaving segment B’s 
image unaffected, do the following sequence of operations: 

a Set A visibility off, 

□ Set dragging on, 

□ Set A visibility on, 

o Drag segment A to the desired location, 

□ Set A visibility off, 

□ Set dragging off, 

□ Set A visibility on. 

See also: set_rasterop (). 

SunCore uses the SunView Notifier to handle signals. Therefore, SunCore appli¬ 
cations should use the Notifier instead of explicit signal () calls. Seethe 
manuals, SunView Programmer’s Manual and SunView System Programmer’s 
Manual. 
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Viewing Operations and Coordinate 

Transforms 


specifying a viewing operation may be thought of as specifying the arbitrary 
orientation of a synthetic camera. The resulting view of the object (the snapshot) 
can appear on one or more view surfaces. The viewing operations are provided 
for two reasons: 

1. To specify how much of the world coordinate space should be visible, and 

2. To specify a mathematical transformation between the world coordinate sys¬ 
tem and NDC space. 

A viewing operation is specified hy a view volume that defines the portion of 
world coordinate space which is to he projected onto a view plane (also called a 
projection plane), and a rectangular viewport in NDC space to which the pro- 
V_. jected image will he mapped. The viewing operation is sufficiently general as to 

support both parallel and perspective projections. The parallel projection 
includes the orthographic, axonometric, isometric, cavalier, and cabinet projec¬ 
tions, as special cases. 

Once the camera model is specified with set_view_ref erence_point (), 
set_view_jplane_normal 0, and so on, a 4 X 4 view transform matrix is 
constructed. Then the process of generating an image on a view surface is: 

1. View-transforming the output primitives (using the view transform preceded 
by any modelling transform the user has specified) to NDC space. 

2. Optional clipping to the window. 

3. Scale the output to map the window to the viewport. 

4. Optional image transformation as specified by dynamic segment attributes. 

5. Optional clipping to the viewport. 

6. Convert to device coordinates and draw the picture. 


3.1. Windows, View 

Volumes, and Clipping 


C' 


The window is the bounded portion of the view plane containing projected 
objects which will appear within the viewport on the view surface. The view sur¬ 
face corresponds to the physical device on which the picture is drawn. The win¬ 
dow is the logical region, specified in world coordinates, in which the image 
appears. 
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n 

Specifying a window involves defining a coordinate system for the view plane. 

The coordinate system for the view plane is called the uvw coordinate system, to 
distinguish it from the world coordinate system and the NDC space, both of 
which are xyz coordinate systems. 

The origin of the uvw coordinate system is at the point where the line through the 
view reference point parallel to the view plane normal vector intersects the view 
plane. In the default case, the view plane distance is zero, and so the view refer¬ 
ence point lies in the view plane and is the origin of the uvw coordinate system. 

The direction of the v-axis is determined from the view up vector. The view up 
vector is specified in world coordinates relative to the view reference point. 

The positive w-axis of the uvw coordinate system is 90 degrees clockwise from 
the positive V axis, as viewed in the direction of the view plane normal vector. 

The positive U and V axes, together with the view plane normal vector, form a 
left handed coordinate system. The window is specified in terms of maximum 
and minimum u and v values (see the set_window () function). Figure 3-1 
shows the various components of the viewing system. 
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I 

^ 3.2. Default Values of 

Viewing Operation 
Parameters 

Table 3-1 Default Values of Viewing Operation Parameters 


Parameter 

Default Value 

View Reference Point 

{0,0.0} 

View Plane Normal 

{0,0,-l} 

View Distance 

0 

Front Distance 

0 

Back Distance 

1 

Type of Projection 

Parallel (0, 0, 1) 
(perpendicular to the uv 
plane) 

Window 

(0, 1,0,0.75) 

View Up Vector 

(0,1,0) 

NDC Space 

0.0<x,z<1.0 

0.0<y^.75 

Viewport 

(0.0, 1.0, 0.0, 0.75,0.0, 1.0) 


Table 3-2 Default Values of Viewing Control Parameters 



Parameter 

Default Value 

Window Clipping 

On 

Output Clipping 

Off 

Front Plane Clipping 

Off 

Back Plane Clipping 

Off 

World Coordinate System 

Right handed 


Table 3-3 World Coordinate Matrix Parameters (Modelling Transform) 


Parameter 

Default Value 


1000 

Identity Matrix 

0 100 

00 10 


000 1 
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Table 3-4 Image Transformation Parameters 


Parameter 

Default Value 

SX, SY, SZ 
AX, AY, AZ 
TX,TY,TZ 

1,1,1 (no scaling) 

0,0,0 (no rotation) 

0,0,0 (no translation) 



3.3. Setting 3D Viewing SunCore provides a number of functions for setting parameters of the viewing 

Operation Parameters operations. There are a number of separate calls available for setting individual 

parameters, then there is a composite set_viewing_parameters () func¬ 
tion which sets all the viewing parameters in one fell swoop. The individual 
calls provided are summarized here and described in detail in the subsections fol¬ 
lowing. 


w 


t I 
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Table 3-5 Summary of Functions for Setting Viewing Control Parameters 


Function 

Description 

set view reference_point 

Sets the view reference point in world 
coordinates. 

set_view_plane_normal 

Defines a vector which determines the 
view plane, relative to the view refer¬ 
ence point. 

set_view_jplane__distance 

Defines the view plane distance from the 
view reference point along the view 
plane normal vector. 

set_view_depth 

Defines the distance ftom the view 
referen^ point to the ‘front’ clipping 
plane (also known as the ‘hither’ or 
‘near’ clipping plane) and the distance 
from the view reference point to the 
‘back’ clipping plane (also known as the 
‘yon’ or ‘far’ clipping plane). 

set_j>r ejection 

Selects perspective or parallel projec¬ 
tion, and defines file center of projection 
(for PERSPECTIVE projection) or direc¬ 
tion of projection (for PARALLEL pro¬ 
jection). 

set view up 2 

Establish the view up direction in the 

set_view_up_3 

view plane for 2 or 3D viewing. 

set_window 

Establishes the window boundaries in 
the view plane. 

set_viewport_2 

Establish the viewport boundaries in 

set_viewport_3 

NDC space for 2 or 3D viewing. 

set_ndc_space_2 

Establish the size of NDC space for 2 or 

set__ndc__space_3 

3D viewing. 

set_viewing_j>arameters 

is a composite function which does all 
of the above functions at one time. 


None of the above calls have any effect until the next call upon the 
create_retained_seginent () or create__temporary_segment () 
functions. 


Establish Reference Point for set_view_reference_j)oint (x, y, z) 

Viewing float x, y, z; /* x, y, and z coordinates */ 

set_view__ref erence_point () sets the view reference point in world 
coordinates, x, y, and z are the coordinates of the view reference point. In the 
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absence of a specified reference point, the default view reference point is 
(0,0,0). The new reference point does not take effect until a new segment is 
created. 


Establish View Plane Normal set_view_plane_nonnal (dx_nonn, dy_norra, dz_nonn) 

Vector float dx_nonn, dy_nonn, dz_norm; 

set_view_plane_normal () defines a vector relative to the view reference 
point, in world coordinates. The view plane is perpendicular to the view plane 
normal vector. In the absence of any information to the contrary, SunCore estab¬ 
lishes the view plane normal vector as (0,0, —1). The new vector does not take 
effect until a new segment is created. 

□ No view plar^ normal direction can be established because dxjtorm, 
dy norm, and dz_norm are all zero. 


Establish View Plane Distance set_view_plane_distance (distance) 

float distance; 

set_view_plane_distance () establishes the view, or projection, plane. 

The view plane is perpendicular to the view plane rrarmal vector, and is distance 
from the view reference point along the view plane normal vector. Distances are 
measured in world coordinate units from the view reference point. Positive 
values of distance correspond to the direction of the view plane normal vector, 
and negative values correspond to the opposite direction. In the absence of any f''~\ 

information to the contrary, distance is set to zero, which means diat the viewing y 
plane is located at the view reference point. 

Select Projection Type set_j>rojection (projection, dx_proj, dy_proj, dz_proj) 

int projection; /* Projection type */ 

/* PARALLEL; PERSPECTIVE */ 
float dx_proj, dy_proj, dz_proj; 

/* X, y, and z Deltas of Projection Point */ 

set_pro jection () selects the projection system for displaying. The argu¬ 
ments dx_proj, dy_proj, and dz_proj specify a world coordinate point relative to 
the view reference point. If projection is PARALLEL, objects project onto the 
view plane along lines parallel to the vector specified by dx_proj, dy j>roj, and 
dz_proj. If projection is PERSPECTIVE, (dx_proJ, dyj?roJ, dz_proj) specify a 
point in world coordinates relative to the reference point called the center of 
projection (often abbreviated to COP). Objects project onto the view plane along 
lines travelling towards this point. Thus the center of projection is the apex of a 
pyramid whose edges pass through the four corners of the view window. 

□ The direction of projection cannot be established because dx, dy, and dz are all 
zero. Note that this error is only applicable if parallel projection was selected. 


Establish 2D View Up Vector set_view_up_2 (dx, dy) 

float dx, dy; /* dx and dy coordinates */ 

set_view_up_2 () establishes a view up vector in 2D. This vector defines 
the direction of ‘up’ for the window in world coordinates. 
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a The view up vector cannot be established because dx, and dy are both zero. 

Establish 3D View Up Vector set_view_up_3 (dx_up, dy_up, dz_up) 

float dx_up, dy_up, dz_up; 

/* X, y, and z Deltas of View Up Vector */ 

set_view_up_3 () establishes a view up vector in 3D. The three arguments 
dx up, dy_up, and dz_up establish a view up vector relative to the view reference 
point. The view up vector, when projected onto the view plane in the direction 
of the view plane normal vector, specifies the positive v-axis of the uvw coordi¬ 
nate system in the view plane. The «-axis is also in the view plane, such that the 
«-axis, the v-axis, and the view plane normal vector form a left handed coordi¬ 
nate system. The v-axis is vertical and the u-axis increases to the right when the 
view plane is mapped onto the view surface. 

SunCore establishes the default view up vector as (0,1,0), which means that the 
y-axis is up. 

If the view plane normal vector is parallel to the y-axis, this does not work and so 
SunCore checks the view transforms for validity when creating a segment. Sun- 
Core may generate the error message: 

'The current viewing specification is inconsistent' 

o No view plane normal direction can be established because dx up, dy up, and 
dzjip are all zero. 

Establish Size of 2D NDC set_ndc_space_2 (width, height) 

Space float width, height; 

set_ndc_space_2 () defines the size of the NDC space which can be 
addressed on the view surface of all display devices available to the applications 
program and within which viewports may be established. Both width and height 
must be in the range of 0.0 to 1.0, and at least one of the parameters must have a 
value of 1.0. NDC space ranges from 0.0 to width in the horizontal direction and 
from 0.0 to height in the vertical direction. The rectangle defined by this func¬ 
tion is mapped to the viewable area of any display device available to the appli¬ 
cation program so that the entire rectangle is visible. Only uniform scaling of the 
rectangle is allowed; no changes can be made to tte viewport aspect ratio. Sun¬ 
Core maximizes the usable area of the display and centers NDC space on each 
view surface. 

The default NDC specification is width= 1.0 and height=0.15. Either of the 
set_ndc_space_2 () or set_ndc_space_3 () (see below) functions may 
be used at most once per initialization of SunCore, and the NDC spacte esta¬ 
blished applies to all view surfaces which the application program might use. 

Ten SunCore functions require that NDC space be established before they com¬ 
plete execution. If NDC space has not been explicitly defined before any of these 
functions are executed, they implicitly define the NDC space using default values. 
Functions which implicitly define NDC space are: 
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Establish Size of 3D NDC 
Space 


o initialize_device() 
o initialize_group() 

□ create_retained_segment () 
o create_temporary_segment0 

□ set_viewport_2 () 

□ set_viewport_3 () 

o set_viewing_parameters() 

□ inquire_viewport_2 () 
o inquire_viewport_3 () 

□ inquire_viewing_paraineters 0 

The depth of NDC space is set to 0.0 if se t_ndc_space_2 () is used in a 3D 
implementation. 

□ set_ndc_space_2 () or set_ndc_space_3 () has already been called 
since the system was initialized. 

□ set_ndc_space_2 ( ) or set_ndc_space_3 () has been called too late 
— the default values have already been defined implicitly. 

□ A parameter is outside the range 0.0 to 1.0. 

o One of width or height must have a value of 1.0. 

□ width or height has a value of 0.0. 




set_ndc_space_3(width, height, depth) 
float width, height, depth; 

set_ndc_space_3 () defines the size of the NDC space which can be 
addressed on the view surface of all display devices available to the applications 
program and within which viewports may be established. 3D NDC space is a rec¬ 
tangular parallelepiped lying within the NDC system. This coordinate system is 
always left-handed, with the x-axis increasing to the right, the y-axis increasing 
upwards, and the z-axis increasing away from the viewer. All of the parameters 
width, height, and depth must be in the itmge of 0.0 to 1.0, and at least one of 
width or height must have a value of 1.0. NDC space ranges from 0.0 to width in 
the horizontal direction, from 0.0 to height in the vertical direction, and from 0.0 
to depth in the direction away from the viewer. The rectangle of size width by 
height in the z=0 plane of NDC space is mapped to the viewable area of any 
display device available to the application program so that the entire rectangle is 
visible. Only uniform scaling of the rectangle is allowed — no changes can be 
made to the viewport aspect ratio. SunCore maximizes the usable area of the 
display and centers NDC space on each view surface. 

The default NDC specification is width=\.Q, height=Q.15, and depth=l.0. Either 
of the set_ndc_space_3 () or set_ndc_space_2 () (see above) func¬ 
tions may be used at most once per initialization of SunCore, and the NDC space 
» established applies to all view surfaces which the application program might use. 
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Ten SunCore functions require that NDC space be established before they com¬ 
plete execution. If NDC space has not been explicitly defined before any of these ^ 
functions are executed, they implicitly define the NDC space using default values. 
Functions which implicitly define NDC space are: 

□ initialize_device() 

□ initiali 2 e_group() 

o create_retained_segment() 
o create_temporarY_segment0 

□ set_viewport_2() 

□ set_viewport_3() 

□ set viewing parameters() 

□ inquire_viewport_2() 
o inquire_viewport_3() 

□ inquire_viewing_parameters(). 

o set_ndc_space_2 () or set_ndc_space_3 () has already been called 
since the system was initialized. 

o set_ndc_space_2 () or set_ndc_space_3 () has been called too late 
— the default values have already been defined implicitly. 

□ A parameter is outside the range 0.0 to 1.0. 

□ One of widrA or/leigAr must have a value of 1.0. 

□ width or height has a value of 0.0. 


Establish a Window in the set_window(umin, umax, vmin, vmax) 

View Plane float umin, umax; /* Left and Right sides of window */ 

float vmin, vmax; /* Bottom and Top of window */ 

set_window () establishes a window, defined by four coordinates in the uv 
coordinate system, in the view plane. SunCore establishes the default window as 
(0.0,1.0,0.0,0.75). 

□ umin is greater than or equal to umax, which means that the left side of the 
window is congruent with or to the right of the right side of the window. 

□ vmin is greater than or equal to vmax, which means that the top of the window 
is congruent widi or below the bottom of the window. 


Specify Planes for Depth set_view_depth (front_distance, back;_distance) 

Clipping float front_distance, backed!stance; 

/* Distances to Front and Back Planes */ 

set_view_depth () defines the front and back planes for depth clipping. 
Clipping to these depth bounds is controlled by 
set_front_j>lane_clipping () and 

set_back j>lane_clipping (). The front and back planes determine the 
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Establish Limits of 2D 
Viewport 


Establish Limits of 3D 
Viewport 


o 

3D view volume which is mapped to the 3D viewport. 

SunCore initializes the front distance to 0.0 and the back distance to 1.0. 

□ frontjiistance is greater than back_distancey so that the back clipping plane is 
in front of the front clipping plane. 

set_viewport_2 (xitiin, xmax, ymin, ymax) 

float xmin, xmax; /* Left and Right sides of Viewport */ 
float ymin^ ymax; /* Bottom and Top of Viewport */ 

set_viewport_2 () establishes the limits of the viewport in 2D NDC space. 

The limits must lie in the range: O^^DCwidth and 0<y <SMNDCheight SunCore 
establishes the viewport to (0.0,1.0,0.0,0.75) at initialization time. 

□ xmin is greater than or equal to xmax^ which means that the left side of the 
viewport is congruent with or to the right of the right side of the viewport. 

□ ymin is greater than or equal to ymax^ which means that the top of the viewport 
is congruent with or below the bottom of the viewport. 

□ Viewport exceeds NDC space. 

set_viewport__3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float xmin, xmax; /* Left and Right sides of Viewport */ 

float ymin, ymax; /* Bottom and Top of Viewport */ 

float zmin, zmax; /* Front and Back of Viewport */ 

set_viewport_3 () establishes the limits of the viewport in 3D NDC space. 

The limits must lie in the range: Q^^DCwidthyQ<y<SMNDCheighty and 
0^<NDCdepth SunCore establishes the viewport to (0.0,1.0, 0.0,0.75,0.0,1.0) 
at initialization time. 

□ xmin is greater than or equal to xmaxy which means that the left side of the 
viewport is congruent with or to the right of the right side of the viewport. 

□ ymin is greater than or equal to ymaxy which means that the top of the viewport 
is congruent with or below the bottom of the viewport. 

□ zmin is greater than or equal to zmax, which means that the front of the 
viewport is congruent with or behind the back of the viewport. 

□ Viewport exceeds NDC space. 



! 
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Set Viewing Parameters 


3.4. Viewing Control 


Enable Clipping in the View 
Plane 


set_viewing_parameters(view_j)arameters) 
struct { 

float vwrefpt[3]; /* x, y, z */ 
float vwplnonn[3]; /* dx, dy, dz */ 

float viewdis; /* View Reference Point to View Plane */ 
float frontdis; /* View Reference Point to Front Clip Plane 
float backdis; /* View Reference Point to Back Clip Plane * 
int projtype; /* PARALLEL or PERSPECTIVE */ 
float projdir[3]; /* Meaning depends on projection type */ 
float window[4]; /* umin, umax, vmin, vmax */ 
float vwupdir[3]; /* dx, dy, dz */ 

float viewport[6]; /* xmin, xmax, ymin, ymax, zmin, zmax */ 
} *view_parameters; 

set_yiewing_parameters () specifies all the viewing parameters with a 
single function call. The view j)arameters argument is a pointer to a stmcture as 
defined above, set viewing parameters () fills in the associated struc¬ 
ture with the current values of the viewing parameters. The parameters are: 

vwrefpt An array of three floats describing the coordinates of the view 
reference point. 

vwplnorm An array of three f loats describing the direction of the view plane 
normal vector. 

viewdis A float describing the distance of the view plane from the view refer¬ 
ence point. 

frontdis A float describing the front clipping distance. 
backxUs A float describing the back clipping distance. 
projtype A int describing the projection type. 

projdir An array of three f loats describing the direction of projection. 

The meaning of projdir is dependent on the projection type: 

PARALLEL projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

window An array of four floats describing the boundaries of the viewing 
window. 


vwupdir An array of three floats describing the view up direction. 

viewport An array of six f loats describing the boundaries of the viewport 


The functions described in the following sections allow the user to control view¬ 
ing attributes like clipping and coordinate systems. 

set_window_clipping(on_off) 

int on_off; /* TRUE = turn clipping on */ 

/* FALSE = turn clipping off */ 
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Enable Front Plane Depth 
Clipping 


Enable Back Plane Depth 
Clipping 


set_winciow clipping () enables or disables clipping against the window 
in the view plane. The argument specifies whether window clipping is 

enabled or not. A value of FALSE disables window clipping, whereas a value of 
TRUE enables window clipping. 

When window clipping is <#, objects described to SunCore are not checked to 
insure that they lie within the window when projected onto the view plane. 
When window clipping is on, objects described to SunCore are clipped to the 
window. 



SunCore initializes window clipping to TRUE. 

Note that window clipping is done before segment primitives are written to the 
pseudo display file. This means that subsequent image transformations may 
extend images beyond the bounds of the viewport SunCore has optional output 
clipping (an extension to the ACM Core specification) to correct for this. See the 
set_output_clipping () function described below. 


set_front_plane_clipping(front_on_off) 
int f ront_on_o f f; 

set_f ront_plane_clipping () enables or disables clipping against the 
front clipping plane. The front_on_qff aigament specifies clipping enabled or 
disabled for the front clipping plane. A value of FALSE means disable the clip¬ 
ping, and a value of TRUE enables the clipping. Clipping is disabled by default 

set_back_plane_clipping(back_on_off) 
int back_on_off; 

set_back_plane_clipping () enables or disables clipping against the 
back clipping plane. The back_on_ojf aipwasat specifies clipping enabled or 
disabled for the back clipping plane. A value of FALSE means disable the clip¬ 
ping, and a value of TRUE enables the clipping. Clipping is disabled by default 




Set Output Clipping (SunCore set_output_clipping (on__of f) 

extension) on_off; /* true = turn on clipping */ 

/* FALSE = turn off clipping */ 

SunCore supports output clipping, which is done after image transformations on 
segments, as an option in addition to window clipping. The 
set_output_clipping () function enables or disables output clipping. If 
output clipping is enabled, it places a clipping process after the image transfor¬ 
mation specified by the dynamic segment attribute. This ensures that everything 
is correctiy clipped to the viewport. 

Set Coordinate System Type set_coordinate_system_type (type) 

int type; /* RIGHT = right handed coordinates */ 

/* LEFT = left handed coordinates */ 

set_coordinate_system_type () selects a left-handed or right-handed 
world coordinate system. 
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Specify 2D World or 
Modelling Transform 


Specify 3D World or 
Modelling Transform 


set_world_coordinate_matrix_2(array) 
float array[3][3]; /* [row] [column] */ 

set_world_coordinate_matrix_2 () specifies a 3 x 3 matrix containing 
the ‘worid transform’ or modelling transform. This matrix is concatenated with 
the ‘viewing transform’ to give the ‘composite viewing transform’. The compo¬ 
site viewing transform is the transform that is actually used for all SunCore view¬ 
ing transfoim operations. The default world coordinate matrix is the identity 
matrix. Currently, this function does not modify column 2 of the matrix. This 
function may be called at any time, even in the midst of putting output primitives 
into a segment. 

Note that the matrix order is such that: 


xnew =x* array g Q+y* array j Q+array ^ g 


ynew =3^ array g i+y*arr<jy xi+array 2 _i 


set_world_coordinate_matrix_3(array) 
float array[4][4]; /* [row] [column] */ 

set_world_coordinate_matrix_3 () specifies a 4 x 4 matrix containing 
the ‘world transform’ or modelling transform. This matrix is concatenated with 
the ‘viewing transform’ to give the ‘composite viewing transform’. The compo¬ 
site viewing transform is the transform that is actually used for all SunCore view¬ 
ing transform operations. The default world coordinate matrix is the identity 
matrix. Currently, this function does not modify column 3 of the matrix. This 
function may be called at any time, even in the midst of putting output primitives 
into a segment 

Note that the matrix order is such that: 


xnew = 1 ^ array Q^+y* array j g+z *array j^Q+array 3 g 


ynew=x*arrayQ^+y*arrayii+z*array2^i-\^array^i 


znew=x*arrayQ^y* array array 2 ^+array^ 2 


Convert 2D NDC to World map_ndc_to_world_2(ndcx, ndcy, wldx, wldy) 

Coordinates float ndcx, ndcy; 

float *wldx, *wldy; 

map_ndc_to_world_2 () maps a point in NDC space to its world coordi¬ 
nates. 
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Convert 3D NDC to World inap_ndc_to_world_3 (ndcx, ndcy, ndcz, wldx, wldy, wldz) 

Coordinates float ndcx, ndcy, ndcz; 

float *wldx, *wldy, *wldz; 

map_ndc_to_world_3 () maps a point in NDC space to its world coordi¬ 
nates. 


Convert 2D World to NDC 
Coordinates 


Convert 3D World to NDC 
Coordinates 


3.5. Inquiring Viewing 
Characteristics 


map_world_to_ndc_2(wldx, wldy, ndcx, ndcy) 
float wldx, wldy; 
float *ndcx, *ndcy; 

map_world_to_ndc_2 () maps a point in world coordinates to its NDC 
space. 

map_world_to_ndc_3(wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz; 
float *ndcx, *ndcy, *ndcz; 

map_world_to_ndc_3 () maps a point in world coordinates to its NDC 
space. 


SunCore provides a number of functions for inquiring about parameters of the 
viewing operations. There are a number of separate calls available for inquiring 
about individual parameters, then there is a composite 

inquire_viewing_parameters () function which obtains all the viewing 
parameters in one fell swoop. The individual calls provided are summarized here 
and described in detail in the subsections following. 


o 




Revision A, of 9 May 1988 





Chapter 3 — Viewing Operations and Coordinate Transforms 39 


Table 3-6 Summary of Functions for Inquiring Viewing Parameters 


Function 

Description 

inquire_view_reference_j)oint 

Obtains the view reference point in world coordinates. 

inquire view plane normal 

Obtains a vector which determines the view plane, relative to 
the view reference point. 

inquire view plane distance 

Obtains the distance from the view reference point to the 
view plane. 

inquire view depth 

Obtains the distance from the view reference point to the 
‘front’ clipping plane (also known as the ‘hither’ or ‘near’ 
clipping plane), and the distance from the view reference 
point to the ‘back’ clipping plane (also known as the ‘yon’ or 
‘far’ clipping plane). 

inquire projection 

Determines which projection type is in use, and returns 
either the center of projection (for PERSPECTIVE projection) 
or direction of projection (for PARALLEL projection). 

inquire view up 2 

Determines the view up direction in 2D. 

inquire view up 3 

Determines the view up direction in 3D. 

inquire_viewport 2 

Obtains the coordinates of the 2D viewport. 

inquire viewport 3 

Obtains the coordinates of the 3D viewport. 

inquire window 

Obtain the boundaries of the viewing window. 

inquire viewing parameters 

is a composite function which does all of the above functions 
at one time. 

inquire ndc space 2 

Determine the size of the NDC space in 2D. 

inquire_ndc_space 3 

Determine the size of the NDC space in 3D. 


Inquire View Reference Point inquire_view_reference_point (x, y, z) 

float *x, *y, *z; /* x, y, and z Coordinates */ 

inquire_view_ref erence_point () obtains the coordinates of the view 
reference point 


Inquire View Plane Normal inquire_view_plane_normal (dx, dy, dz) 

float *dx, *dy, *dz; /* x, y, and z deltas */ 

inquire_viewj)lane_normal () obtains the coordinates of the view 
plane normal vector. 


Inquire View Plane Distance 


inquire_view_plane_distance(view_distance) 
float *view_distance; 

inquire_view_plane_distance () obtains the distance of the view 
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Inquire View Depth 


Inquire Projection 


Inquire View Up 2 


Inquire View Up 3 


Inquire NDG Space 2 


Inquire NDC Space 3 


Inquire Viewport 2 


Inquire Viewport 3 


Inquire Window 


plane from the view reference point. 

inquire_view_depth (fronted!stance,- back__distance) 
float *front_distance, *back___distance; 

inquir e_view_depth ( ) obtains the distances of the front and back clipping 
planes from the view reference point. 

inquirej>ro jection (pro jection__type,^ dx,^ dy, dz) 
int *projection_type; 

float *dx, *dy, *dz; /* x, y, and z deltas */ 

inquire^jpro ject ion () obtains the current projection type and the coordi¬ 
nates of the center of projection (for PERSPECTIVE projections) or the direction 
of projection (for PARALLEL projections). 

inquire_view_up_2 (dx, dy) 

float *dx, *dy; /* x and y directions */ 

inquire_view_up_2 () obtains the view up direction in 2D. 
inquire_view_up_3 (dx^ dy, dz) 

float *dx, *dy, *dz; /* x, y, and z directions */ 

inquire_view_up_3 () obtains the view up direction in 3D. 

inquire_ndc_space_2(width, height) 
float *width, *height; 

inquire_ndc_space_2 () obtains the dimensions of the 2D NDC space. 

inquire_ndc_space_3(width, height, depth) 
float *width, ^height, *depth; 

inquire_ndc_space_3 () obtains the dimensions of the 3D NDC space. 

inquire_viewport_2 (xmin, xmax, ymin, ymax) 
float *xmin, *xmax; 
float *ymin, *yinax; 

inquire_viewport_2 () obtains the coordinates of the 2D viewport. 

inquire_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float *xmin, *xmax; 
float *ymin, *ymax; 
float *zmin, *zmax; 

inquire_viewport_3 () obtains the coordinates of the 3D viewport. 

inquire_window (umin, umax, vmin, vmax) 
float *umin, *umax; 
float *vmin,. *vmax; 

inquire_window () obtains the boundaries of the viewing window. 
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Inquire Viewing Parameters 


r 


inquire^viewing_j:>arameters (view_parameters) 
struct { 

float vwrefpt[3]; /* x, Yf z */ 
float vwplnorm[3]; /* dx, dy^ dz */ 

float viewdis; /* View Reference Point to View Plane */ 
float frontdis; /* View Reference Point 
to Front Clip Plane */ 
float backdis; /* View Reference Point 
to Back Clip Plane */ 

int projtype; /* PARALLEL or PERSPECTIVE */ 
float projdir[3]; /* Meaning depends 
on projection type */ 

float window[4]; /* umin, umax^ vmin, vmax */ 
float vwupdir[3]; /* dx, dy, dz */ 
float viewport[6]; /* xmin^ xmax^ ymin, 
ymax, zmin^ zmax */ 

} *view_j>arameters; 

inquire viewing parameters () returns a collection of inforaiation per- 
taining to the current parameters of the viewing system. The view j>arameters 
argument is a pointer to a structure as defined above. 

inquire__viewing_parameter s () fills in the associated structure with 
the current values of the viewing parameters. The parameters are: 

vwrejpt An array of three floats describing the coordinates of the view 
reference point. 

vwplnorm An array of three floats describing the direction of the view plane 
normal vector. 

viewdis A f loat describing the distance of the view plane from the view 
reference point. 

frontdis A f loat describing the front clipping distance. 
backdis A float describing the back clipping distance. 
projtype A int describing the projection type. 

projdir An array of three floats describing the direction of projection. 

The meaning of projdir is dependent on the projection type: 

PARALLEL 

projdir specifies the direction of projection. 

PERSPECTIVE 

projdir specifies the center of projection. 

window An array of four floats describing the boundaries of the viewing 
window. 

vwupdir An array of three f loat s describing the view up direction. 
viewport An array of six f loat s describing the boundaries of the viewport. 
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Inquire World Coordinate 
Matrix 2 


Inquire World Coordinate 
Matrix 3 


Inquire Inverse Composite 
Matrix (SunCore Extension) 


Inquire Viewing Control 
Parameters 





inquire__world_coordinate_matrix___2 (array) 
float array[3][3]; /* array[row][col] */ 

inquire__world_coordinate_matrix_2 () returns a 3 by 3 matrix con¬ 
taining the ‘world transform’ or modelling transfonn. This matrix is con¬ 
catenated with the ‘viewing transform’ to give the ‘composite viewing 
transform’. The composite viewing transform is the transform that is actually 
used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 


inquire_world_coordinate_]:natrix_3 (array) 
float array[4][4]; /* array[row][col] */ 

inquire_world_coordinate_matrix_3 () returns a 4 by 4 matrix con¬ 
taining the ‘world transform’ or modelling transform. This matrix is con¬ 
catenated with the ‘viewing transform’ to give the ‘composite viewing 
transform’. The composite viewing transform is the transform that is actually 
used for all SunCore viewing transform operations. The default world coordinate 
matrix is the identity matrix. 


inqui re_in ver s e_compo s it e_jna t r ix (a r r ay) 
float array[4][4]; /* array[row][col] */ 

SunCore uses the matrix inverse of the composite viewing transform internally 
for operations such as map_ndc_to_wor Id (). This matrix may at times be 
useful to the applications program. 



inquire_viewing__control_parameters (windowclip, 
frontclipf backclip, type) 

int *windowclip; /* TRUE if window clipping enabled */ 
int *frontclip; /* TRUE if front plane clipping enabled */ 
int *backclip; /* TRUE if back plane clipping enabled */ 
int *type; /* RIGHT or LEFT world coordinate system type */ 

inquire_viewing_control j>arameter s () obtains the enabled status 
of clipping, and the type of world coordinates in use. 
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Segmentation and Naming 



4.1. Retained Segment 
Attributes 



All output primitives for a graphical object are placed in a segment by SunCore 
on request from the application program. Each segment defines an image which 
is a view of the object and which is part of the picture displayed on the view sur¬ 
face. An application program describes an object by creating a segment, calling 
outfHit primitive functions (the results of which are placed in the segment), and 
then closing the segment 

There are two kinds of segments, namely: temporary segments and retained seg¬ 
ments. Retained segments have an image transformation type which specifies 
how they can be transformed. Retained segments can be made visible or invisi¬ 
ble, detectable (via the pick input function) or undetectable, highlighted, and may 
be transformed, depending on their type. 

Retained segments have names (actually numeric identifiers) so that by placing 
output primitives in such segments, the application programmer can selectively 
modify parts of the picture by deleting and recreating segments (which effec¬ 
tively replaces them) so that their images change. Retained segments are stored 
in the display list for later dynamic modification. 

Temporary segments are not saved in the display list, are only drawn once, and 
may not be modified dynamically. A new frame action deletes all portions of any 
temporary segments which have already been drawa 

In the same way that primitive attributes affect the output primitives, retained 
segment dynamic attributes affect the characteristics of retained segments. From 
now on, the term dynamic attributes means the dynamic attributes of retained 
segments. 

As well as being identified by the name of the retained segment into which they 
have been placed, output primitives may also be assigned a primitive attribute 
known as a pick identifier or pick-id. This means that within the single level of 
segmentation, another level of naming is provided. An example of the use of 
pick-id might be that all the character strings for (say) a menu could appear in a 
single segment, where each character string is assigned a different pick-id. Then 
when the user is using the mouse to select a specific item from the menu, the 
application program uses the PICK input function to find out which menu item 
was selected. 
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Retained segments have one static attribute and four dynamic attributes. Attri¬ 
butes, and the means of setting them and inquiring their values, are described in 
detail in Chapter 6. 

The only static attribute of retained segments is the image transformation type. 
This attribute can have one of five values: 

None 

The segment is a retained segment on which no transformations may be 
applied. 

Translatable 2D 

The segment is a retained segment which may be translated in 2D. 
Transformable 2D 

The segment is a retained segment which may be fiilly translated, scaled, 
and rotated, in 2D. 

Translatable 3D 

The segment is a retained segment which may be translated in 2 or 3D. 
Transformable 3D 

The segment is a retained segment which may be fully translated, scaled, 
and rotated, in 2 or 3D. 

SunCore sets image transformation type to the default value of NONE at initiali¬ 
zation time. 

The four dynamic attributes of retained segments are defined here. 

Visibility 

indicates whether the segment should have a visible image. There are only 
two values of this attribute, namely: TRUE and FALSE. 

SunCore sets the default value of visibility to TRUE at initialization time. 

Highlighting 

indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by blinking. There are only two values of the highlight¬ 
ing attribute, namely: TRUE and FALSE. When highlighting is turned on, 
the segment is blinked once. 

SunCore sets the default value of highlighting to FALSE at initialization 
time. 

Detectability 

indicates whether the retained segment can be detected by the pick device 
(mouse pointing device). See the awalt_j5ick () function. The values 
for the detectability attribute, are: 0 through 2,147,483,647. SunCore sets 
the default value of detectability to 0 at initialization time. 

Image Tran^ormation 

indicates how the image of a retained segment, in NDC space, is scaled, 
rotated, or translated. A segment’s static image transformation type attribute 
limits the values which its image transformation attribute may have. See the 
set of functions called set_seginent_image_jbac() in Chapter 6. 
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4.2. Retained Segment 
Operations 


Create a New Segment 


Close a Segment 


Delete a Retained Segment 


SunCore sets the default value of image transformation to the identity 
transformation at initialization time. 

A retained segment is a form of storage for graphical primitives. This kind of 
segment remains for the duration of a SunCore application program unless it is 
deleted. After the program exits the contents of a retained segment are lost. 

create_retained_segment (seginent_name) 

int segment_name; /* Segment Identifier */ 

create_retained_segment () creates a new, empty, open segment. The 
segment_name argument defines a segment number in the range 1 through 
2,147,483,647. 

The image transformation type for the newly created segment is obtained from 
the current attribute value for image_transf ormation_tYpe. The 
dynamic attribute values for the newly created segment are obtained ftom the 
default values of the dynamic attributes for retained segments. 

Use the set_image_transf ormation_^type ( ) function, before calling 
Greate_retained_segment () , to specify whether the created segment is 
translatable or transformable. After calling 

create_retained_segment (), the specified segment is said to be 
“open”. This means that output primitives can now be called upon to add 
graphics primitives (lines, text, polygons, and so on) to this segment. 

Only one segment can be open at a time. 

□ The set of currently selected view surfaces is empty. 

□ The current viewing specification is inconsistent. 

□ There is already an open segment. 

□ A retained segment named segment_name already exists. 

□ The default value of image_transf ormation is invalid for the current 
image_transf ormation_type. 

close_retained_segment() 

close_retained_segment () closes the currently open segment. Dynamic 
segment attributes may be changed both before and after closing the segment. 

□ There is no open retailed segment. 

delete_retained_segment(segment_name) 

int seginent_name; /* Segment Identifier */ 

delete_retained_segment 0 deletes a specifically named segment. The 
segment specified by the segment_name argument is deleted. If the segment 
being deleted is the currently open segment, it is closed before it is deleted. The 
deleted segment is erased from all view surfaces. 
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□ There is no retained segment with the name segment__name. 

Rename a Retained Segment renaine_retained_seginent (segment_naine^ newname) 

int seginent__name; /* Old Segment Identifier */ 
int newname; /* New Segment Identifier */ 

r ename_r et ained_segment () changes the name of a retained segment. 

The segment whose identity is segment_name is renamed as newname, and 
this name must be used in any future references to that segment. The segment 
segment^name is no longer accessible. 

□ There is no retained segment with the name segment_name. 

□ There is an existing retained segment named new__naine. 


Delete All Retained Segments delete_all_retained_segments () 

delete_all__retained.__segments () deletes all retained segments. All 
retained segments are deleted. If there is a currently open retained segment, it is 
closed before it is deleted. 

Inquire Retained Segment 
Surfaces 


inqTaire_retained_segment_surf aces () obtains the number and 
names of the view surfaces upon which this segment gets drawn. These view 
surfaces were ‘selected’ when the segment was created. The number of view sur¬ 
faces selected at the time the retained segment name given by segment_name 
was created is copied into nuinber_of_sur faces. The names of those sur¬ 
faces are copied into view_surf ace_array, where the array is an array of 
view surface names. array_size is specified by the caller, and is the size of 
view_sur f ace_array. The view surface structure is defined in the 
<usercore. h> header file. 

If number_of_sur faces is greater than array size, only array_size 
view surface names are copied into viewjsurface_array. If array_size is less 
than or equal to zero, no names are returned. 

□ There is no retained segment with the name segment_name. 


inquire_retained_segTnent_surfaces (segment_name^ 

array_size, view_surface_arrayf nuitiber__of_surfaces) 
int segment_naine; /* Name of Segment */ 

int array_size; /* Size of View Surface Array */ 

struct vwsurf view_surface_array[]; 

/* Array of view surface names */ 
int *number__of_surfaces; 

/* Returned number of surfaces */ 


o 


Inquire Retained Segment 
Names 


inquire_retained_segment_names (array_size, 
name_array, number_of_segments) 
int array_size; /* Size of Array */ 

int name__array []; /* Segment Identifiers */ 

int *number_of_segments; /* Number of Segments */ 

inquire_retained_segment_names () obtains a list of the retained seg¬ 
ments names. The name_array argument is an array which is to receive a list 
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Inquire Open Retained 
Segment 


4.3. Temporary or Non- 
Retained Segments 


Create Temporary Segment 


Close Temporary Segment 


Get Temporary Segment 
Status 


4.4. Saving and Restoring 
Segments on Disk 


Save Segment on Disk File 
(SunCore Extension) 


of the existing retained segments. arraY_size specifies the number of ele¬ 
ments in name_arraY. The number_ofsegments argument is returned to the 
caller, and is the number of existing retained segments. If the number of existing 
retained segments is greater than the size of the array, only array_size seg¬ 
ment names are copied into the array. If array_size is less than or equal to 
zero, no segment identifiers are returned. 

inquire_open_retained_segTOent(segment_name) 
int *segment_name; /* Segment Name */ 

inquire_open_retained._segment () obtains the name of the currently 
open retained segment The name of the currently open retained segment (if 
there is one) is copied into the segment_name variable. If there is no currently 
open retained segment, segment_name is set to zero. 

Temporary segments are used for transient images. Temporary segments carmot 
be modified dynamically, and all portions of temporary segments which have 
already been drawn are deleted upon any new frame action. Primitives placed in 
temporary segments are not stored in the display list. 

create_temporary_segmentO 

create_temporary_segment () creates a new, empty, nonretained or tem¬ 
porary, segment. 

close_temporary_segment0 

close_temporary_segment () closes the currently open temporary seg¬ 
ment. 

inquire_open_temporary_segment(open) 

int *open; /* Receives status of temporary segment */ 

inquire_open_teitiporary_segment () determines whether there is a 
currently open temporary segment. The open argument receives the status of 
whether there is a currently open temporary segment: 

FALSE There is no currently open temporary segment. 

TRUE There is a currently open temporary segment. 


The two functions described in this section provide for saving segments on disk 
files and restoring segments from disk files. Only one segment is saved in a 
given file. 

save_segment(segment_name, filename) 

int segment_^name; /* Name of segment to save */ 

char *filename; /* Pointer to a filename */ 

save_segment () saves the named retained segment on a specified disk file. 
Saved primitives are in NDC space. Dynamic segment attributes are also saved. 
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Restore Segment from Disk 
File (SunCore Extension) 



restore_segment (seginent_name, filename) 

int segment_name; /* Name of segment to create */ 

char *filename; /* Pointer to a filename */ 

restore_segment () restores the named retained segment from a specified 
disk file. A new segment is created and the segment from the disk file is copied 
into it. The segment is then closed. 
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Output Primitives 




Output Primitives serve to describe objects in the world coordinate system. 
When the output primitive functions are called, primitives are placed in the 
currently open segment via drawing commands which eventually produce line 
and character output. 

SunCore supports six kinds of output primitives, namely moves, lines and poly¬ 
lines, polygons, text, markers and polymarkers, and rasters. The table below 
summarizes these types of functiom: 

Table 5-1 Summary of Output Primitive Functions 


Primitive 

Description 

Move 

primitives alter the value of the current position 
(described below). 

Line 

primitives describe lines in world coordinates. 

Polyline 

primitives describe sequences of coimected lines in 
world coordinates. 

Polygon 

primitives describe a closed polygon which will be filled 
with a color. The polygon primitives are a SunCore 
extension to the ACM Core specification. 

Text 

primitives describe character strings on the display. 

Marker 

primitives describe markers which are written on the 
display in a constant orientation, independent of any 
transformations which may be in effect. 

Polymarker 

primitives describe a sequence of markers which are 
written on the display in a constant orientation, indepen¬ 
dent of any transformations which may be in effect. 

Rasters 

primitive describes an array of one-bit or eight-bit pix¬ 
els. 


All primitive operations use world coordinates. Some of these operations affect 
the value known as the current position. The current position defines the current 
drawing location in the world coordinate system. SunCore maintains the value 
of the current position at all times. At initialization time, the current position is 
initialized to the origin of the world coordinate system. 
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In both 2 and 3D, coordinate positions can be specified in terms of absolute 
world coordinates, or coordinates can be specified relative to the current position. 



A segment must be open (see the create_xaca:_segment () functions) 
before any output primitives may be used. A segment contains a set of output 
primitives which can subsequently be manipulated as a unit. 


An output primitive is processed as follows: 


1. The primitive is transformed to clipping coordinates using the composite 
viewing transform. This places the window boundaries at umin=-32767, 
Umax =+32767, v/m/i=—32767, and vmax=+32167. The front clipping plane is 
at z =0 and the back clipping plane is at z =+32767. 

2. The primitive is then clipped to the boundaries just mentioned if window 
clipping is enabled. 

3. The output primitive is then output scaled to the viewport which is specified 
in NDC space. 

4. The resulting primitive is then copied to display list or pseudo display 
file (PDF) if the open segment is a retained segment. 


5. Next, the primitive is transformed using the image transform which is an 
attribute of retained translatable or retained transformable segments. 


6 . 

7. 


The output primitive is then clipped again to the viewport boundaries if out¬ 
put clipping is enabled. 

For each view surface which was selected when the segment was created, the 
primitive is then converted to physical device coordinates and drawn on the 
view surface. 



If a change is made to certain dynamic segment attributes of a retained segment, 
the primitives in that segment are recovered from the PDF and used to erase the 
. segment (if necessary) and redraw the segment following steps 5 through 7 
above. The diagram below shows the above process in a graphical form. 


w 
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Figure 5-1 Flow Diagram of Output Primitive Processing 
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5.1. Moving the Current 
Position 


Move to Absolute 2D Position 


Move to Absolute 3D Position 


Move to Relative 2D Position 


Output primitives are drawn with the static primitive attributes set by the primi¬ 
tive attribute functions (see Chapter 6). 

There are four functions for moving the current position. move_abs_2 () and 
move_abs_3 () change the current position to an absolute position in world 
coordinates, whereas move_rel_2 () and move_rel_3 ( ) change the current 
position by a delta relative to the current position. 

Note that move_abs_2 () and move_rel_2 () are simply short forms of the 
corresponding 3D functions. The z coordinate of move_abs_2 () is the z coor¬ 
dinate of the current position. The z delta of move_rel_2 () is taken as zero. 

move_abs_2 (x, y) 

float X, y; /* X and y coordinates to move to */ 

move_abs_2 () moves the current position to an absolute position. The 
current position is set to the values of x and y in 2D world coordinates. 
inove_abs_2 () only sets the current position; no drawing commands are out¬ 
put. 

move_abs_3(x, y, z) 

float X, y, z; /* x, y, and z coordinates to move to */ 

move_abs_3 () moves the current position to an absolute position. The 
current position is set to the values of x, y, and z in 3D world coordinates. 
move_abs_3 () only sets the current position; no drawing commands are out¬ 
put. 

move_rel_2(dx, dy) 

float dx, dy; /* x and y coordinate deltas */ 

move_rel_2 () increments the current position by the values given. The 
current position is set to the value of current position plus dx and dy in 2D world 
coordinates. move_rel_2 () only sets the current position; no drawing com¬ 
mands are output. 


Move to Relative 3D Position 


5.2. Position Inquiry 
Functions 


move_rel_3(dx, dy, dz) 

float dx, dy, dz; /* x, y, and z coordinate deltas */ 

move_rel_3 () increments the current position by the values given. The 
current position is set to the value of current position plus dx, dy, and dz in 3D 
world coordinates. move_rel_3 () only sets the current position; no drawing 
commands are output. 

The position inquiry functions return the coordinates of the current position to 
the caller. 


Inquire 2D Position 


inquire_current_position_2(x, y) 
float *x, *y; 

inquire_current j>osition_2 () returns the 2D world coordinates of 
the current position to the caller. 
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Inquire 3D Position ^ ^, 

^ inquire_current_position_3<x, y, z) 

float *x, *y, *z; 

inquire_current_position_3 ( ) returns the 3D world coordinates of 
the current position to the caller. 

5.3. Line Functions The line functions draw lines on the currently selected SunCore view surfaces. 

Attributes of the line can be specified with additional calls to primitive attribute 
setting functions. 

The primitive attributes of line index, linestyle, linewidth, and pick id are appli¬ 
cable for lines. 

□ There is no open segment. 

Describe Line in Absolute 2D line_abs_2 (x, y) 

Coordinates float x, y; 

line_abs_2 () describes a line in 2D world coordinates. The line that 
line_abs_2 ( ) describes extends from the current position to the position 
specified by the jc and y coordinates. 

The current position is updated to the coordinates specified by x and y. 

Describe Line in Absolute 3D line_abs_3 (x, y, z) 

Coordinates float x, y, z; 

line_abs_3 () describes a line in 3D world coordinates. The line that 
line_abs_3 () describes extends from the current position to the position 
specified by the x, y, and z coordinates. 

The current position is updated to the coordinates specified by x, y, and z. 

Describe Line in Relative 2D line_rel_2 (dx, dy) 

Coordinates float dx, dy; 

line_rel_2 () describes a line in 2D worid coordinates. The line that 
line_rel_2 () describes extends from the current position to the position 
specified by the current position plus the dx and dy coordinates. The current 
position is updated by the deltas specified by dx and dy. 

Describe Line in Relative 3D line_rel_3 (dx, dy, dz) 

Coordinates float dx, dy, dz; 

line_rel_3 () describes a line in 3D world coordinates. The line that 
line_rel_3 ( ) describes extends from the current position to the position 
specified by the current position plus the dx, dy, and dz coordinates. 

The current position is updated by the deltas specified by dx, dy, and dz. 
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5.4. Polyline Functions 


Describe Line Sequence in 
Absolute 2D Coordinates 


Describe Line Sequence in 
Absolute 3D Coordinates 


Describe Line Sequence in 
Relative 2D Coordinates 


Describe Line Sequence in 
Relative 3D Coordinates 


The polyline functions describe connected sequences of lines. The first two or 
three arguments to a polyline function are arrays of the appropriate coordinates. 
Consider the polyline function: 

polyline_abs_3 (x^array, y_array, z__array, n) 
float x__array[], y_array[], z_array[]; 

/* y, and z arrays */ 
int n; /* Number of coordinates */ 

The sequence of lines that these arrays of coordinates describe starts at the 
current position, then draws to: {xjirray[0], y_array[0], zjarray[0])^ then runs 
through the intermediate array values and ends at (x array[n- 1 7 , y array[n- 1 7 , 
zjarray[n-l]) where n is the number of elements in each of the coordinate arrays. 
TTiere are thus n lines in the figure described. 

□ The number of coordinates, n, is less than or equal to zero. 

□ There is no open segment. 


polyline__abs__2 (x__array, y__array, n) 

float x_array[]r y_array[]; /* x and y coordinates */ 
int n; /* number of array elements */ 

polyline_abs_2 () describes a line sequence in absolute 2D world coordi¬ 
nates. The current position is updated to the end of the last line drawn. 


polyline_abs_3 () describes a line sequence in absolute 3D world coordi¬ 
nates. The current position is updated to the end of the last line drawn. 


polyline_abs_3 (x_array^ y_array, z_arrayf n) 
float x_array[]/ y__array[]/ z_array[]; 

/* X, y, and z arrays */ 
int n; /* number of elements */ 


polyline_rel_2 (dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y delta arrays */ 
int n; /* number of array elements */ 

poly line_rel_2 () describes a line sequence in relative 2D world coordi¬ 
nates. The sequence of lines that this function describe starts at the current posi¬ 
tion, moves to: current position + dx array [0], ( dy array [0]) then draws to: 
current position + dx_array [0], ( dy array [0]) + dx array [1], ( dy array [1]) 
and so on. The current position is updated to the end of the last line drawn. 


polyline_rel_3 (dx_array, dy__array, dz_array, n) 
float dx__array [ ], dy_array [ ], dz__array [ ] ; 

/* X, y, and z delta arrays */ 
int n; /* number of elements */ 


polyline_rel_3 () describes a line sequence in relative 3D world coordi¬ 
nates. The sequence of lines that this function describe starts at the current posi¬ 
tion, moves to: current position + dxjirray [0], ( dy array [0], dz array [0]) 
then draws to: current position -h (dxarrayfO], dyarray[0], dz_array[0J) -h 
(dx_array[l ], dy_array[1 ], dz_array[1]) and so on. The current position is 
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5,5. Text Functions 


Draw Character String In 
World Coordinates 


updated to the end of the last line drawn. 

The functions described in the next section describe the text facilities available in 
SunCore. The inquiry functions that follow can be used to determine characteris¬ 
tics of text 

text(string); 
char *string; 

text () draws a character string in world coordinates. The character string 
specified by string is drawn from the current position. The current position is 
unchanged. The font, size, orientation, and so on, are set by calls to the set prim¬ 
itive attribute functions. 

□ There is no open segment. 

□ The character string contains one or more characters which carmot be drawn. 

□ The vectors that the current charpath and charup attributes describe are paral¬ 
lel. 


5.6. Text Inquiry Functions 




Text inquiry functions obtain the length that a character string would extend, in 
world coordinates, if the character string were actually drawn according to the 
current text primitive attributes. 

□ inquire_text_extent_2 () was used to obtain the current position 
when inquire_text_extent_3 () should have been used in order to 
avoid loss of information. 


o The character string contains one or more characters which carmot be drawn. 


□ The vectors that the current charpath and charup attributes describe are paral¬ 
lel. 


Inquire Text Extent 2 


Inquire Text Extent 3 



inquire_text_extent_2(string, dx, dy) 
char *string; 
float *dx, *dy; 

inquire_text_extent_2 () returns the extent of the character string 
specified by string, if the character string were drawn, unjustified, from the 
current position. The extent is returned in dx and dy in world coordinates relative 
to the current position. 

The specified character string, and the values of the primitive attributes 
charup, charsize, charpath, charspace, and charprecision are used to calculate 
the vector which represents the extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful 
values if charprecision is CHARACTER. 

inquire_text_extent_3(string, dx, dy, dz) 

char *string; 

float *dx, *dy, *dz; 

inquire_text_extent_3 () obtains the 3D extent, in world coordinates, of 
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the specified character String. inquire_text_extent_3 () returns the 
extent of the character string specified by string, if the character string were 
drawn, unjustified, from the current position. The extent is returned in dx, dy, 
and dz in world coordinates relative to the current position. 



The specified character string, and the values of the primitive attributes font, 
charup, charsize, charpath, charspace, and charprecision ate used to calculate 
the vector which represents the extent of the character string. 

In the current implementation of SunCore, this function only returns meaningful 
values if charprecision is CHARACTER. 


5.7. Marker Functions 


Plot Marker at Absolute 2D 
Coordinates 


The marker functions place a character at a specific location on the display. The 
polymarker functions place a character at a sequence of locations on the display. 

The marker character is any printable ASCII character, and is the value of the 
marker_syiribol primitive attribute. Theinarker_syiabol primitive attri¬ 
bute is set by the set_marker_sYinbol () function described in Chapter 6. 

The markers are placed on the display without any of the rotations, translations, 
or scaling which is applied to text strings. Markers use the default orientation 
attributes. 

□ There is no open segment. 
marker_abs_2 (x, y) 

float X, y; /* Absolute x and y Coordinates */ 

marker_abs_2 ( ) plots a marker at specified absolute 2D world coordinates. 
marker_abs_2 () plots the marker at the absolute 2D coordinates specified by 
the X and y arguments. The current position is updated to be this point. 


Plot Marker at Absolute 3D 
Coordinates 


marker_abs_3(x^ y, z) 

float X, y, z; /* Absolute x, y, and z Coordinates */ 

marker_abs_3 () plots a marker at specified-absolute 3D world coordinates. 
marker_abs_3 () plots the marker at the absolute 3D coordinates specified by 
the X, y, and z arguments. The current position is updated to be this point. 


Plot Marker at Relative 2D 
Coordinates 


Plot Marker at Relative 3D 
Coordinates 


marker_rel_2 (dx, dy) 

float dx, dy; /* x and y Coordinate Deltas */ 

marker_rel_2 () plots the marker at the position relative to the current posi¬ 
tion, specified by the deltas dx and dy. The current position is updated to be this 
point. 


niarker_rel_3 (dx, dy, dz) 

float dx, dy, dz; /* x, y, and z Coordinate Deltas */ 

marker_rel_3 () plots a marker at a specified relative 3D position. 
marker_rel_3 () plots the marker at the position relative to the current posi¬ 
tion, specified by the deltas dx, dy, and dz. The current position is updated to be 
this point 
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Plot Marker Sequence at 
Absolute 2D Coordinates 


Plot Marker Sequence at 
Absolute 3D Coordinates 


Plot Marker Sequence at 
Relative 2D Coordinates 


polymark:er_abs_2 (x_array, y_array, n) 

float x_array[], y_array[]; /* Absolute x and y */ 

int n; /* Number of Coordinates */ 

polYmarker_abs_2 ( ) plots a sequence of maikers at specified absolute 2D 
positions. polymarker_abs_2 () plots a sequence of markers at the absolute 
positions specified by the x array and y_array arguments, n specifies the 
number of coordinates in the arrays. The current position is updated to be the 
last point. 

polymarker_abs_3(x_array, y_array, z_array, n) 
float x_array[], y_array[] , z_array[]; 

/* Absolute X, y, and z */ 
int n; /* Number of Coordinates */ 

polymarker_abs_3 () plots a sequence of maricers at specified absolute 3D 
positions. polymarker_abs_3 () plots a sequence of markers at die absolute 
positions specified by the x array, y array, and z array arguments. The number 
of coordinates in the array is given by the n argument. The current position is 
updated to be the last point 

polymarker_rel_2(dx_array, dy_array, n) 

float dx_array[], dy_array[]; /* x and y Deltas */ 

int n; /* Number of Coordinates */ 

polymarker_rel_2 () plots a sequence of markers at specified relative 2D 
positions. polymarker_rel_2 () plots a sequence of markers at the posi¬ 
tions relative to the current position, specified by the deltas dx_array and 
dy array. The number of deltas in the arrays is specified by n. The current posi¬ 
tion is updated to be the last point 



Plot Marker Sequence at 
Relative 3D Coordinates 


polymarker_rel_3 <) plots a sequence of markers at specified relative 3D 
positions. polymarker_rel_3 () plots a sequence of markers at the posi¬ 
tions relative to the current position, specified by the deltas dx_array, dy_array, 
and dz array. The number of deltas in the arrays is specified by n. The current 
position is updated to be the last point 


polymarker_rel_3(dx_array, dy_array, dz_array, n) 
float dx_array[], dy_array [], dz_array[]; 

/* X, y, and z Deltas */ 
int n; /* Number of Coordinates */ 


5.8. 3D Polygon Shading 
Parameters (SunCore 
Extension) 


When drawing 3D polygons on the Sun color displays, several shading options 
are available. The functions described in this section provide shading control. 
These shading parameters may be changed at any time and are not stored in the 
display list Therefore a segment may be drawn with fast shading at one time, 
and then drawn again later with smooth shading. 
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Set Shading Parameters set_shading_j>aranieters {ambient, diffuse, 

specular, flood, bump, hue, style) 
float ambient; /* percent background light */ 
float diffuse; /* percent diffuse reflection */ 
float specular; /* percent specular reflection */ 
float flood; /* percent flood lighting */ 
float bump; /* specular power 2 ..9 */ 
int hue; /* color index range to generate */ 

/* 0 = 0 .. 255, 1=0.. 63 */ 

/* 2 = 64 .. 127, 3 = 128 .. 191 */ 

/* 4 = 192 .. 255 */ 

int style; /* Type of surface shading to do: */ 

/* CONSTANT, GOURAUD, PHONG */ 

set__shading_parameter s () specifies the parameters for rendering 3D 
polygons on the color display. See set_polygon_interior__style () for 
the ways in which these shading parameters are used. CONSTANT style shading 
gives constant intensity over the polygon using the color set by 
set__f ill_index (). GOURAUD style shading linearly interpolates between 
vertices where the intensity at each vertex is set by the 

set_vertex_indices () function. PHONG style shading produces smooth 
shading using the other parameters (only with convex polygons). 

The equation used for PHONG style shading is: 

pixels hade =ambient +diffuse (L WV y^specular {H WV -(flood* z ) 

where L is the direction vector of the light source, N is the surface normal vector, 
H is a vector which is the average of L and E (the eye direction vector), and z is 
depth in NDC. 

Here are some useful sets of PHONG parameters: 

Table 5-2 2 Useful PHONG Parameters 


Parameter 

Value 

Value 

ambient 

0.05 

0.05 

diffuse 

0.94 

0.74 

specular 

0.0 

0.20 

flood 

0.0 

0.0 

bump 

0.0 

7.0 

hue 

0 

0 


Specify Direction of Light 
Source 

set_light_direction {) specifies the direction of the light source from 
the object. This assumes NDC space where the direction from object to viewer is 
always {0.0,0.0, ~1.0}. Hence, to place the light source at the viewer, the light 
direction is (0.0,0.0, -1.0). The light direction vector is only used if the shading v. 

style is GOURAUD or PHONG. A useful light direction is (-0.2, 0.2, -1.0). 


set_light_direction(dx, dy, dz) 
float dx, dy, dz; 
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Set Vertex Normals 

set_vertex_normals(xlist, ylist, zlist, n) 
float xlist[], ylist[], zlist[]; 
int n; 

set_vert ex normals () sets the surface normal vectors for each vertex of 
the subsequent 3D polygon primitives (polygonabs_3() or polygon- 
re 1_3 ()). These normals are used for PHONG style shading. For GOURAUD 
style shading, use set_vertex_indices {). The number of elements in the 
list, rt, must be equal to the number of vertices in the subsequent call to 
polygonxrc_3 (). 

Set Vertex Indices set_vertex_indices (color_index_list, n) 

int color_index_list[]; 
int n; 

set_vert ex_indices () specifies a color index for each vertex of the next 
polygonxxx_3 () primitive. GOURAUD shading linearly interpolates these 
color indices for smooth shading in the interior of the polygon. The number of 
elements in the list, n, must be equal to the number of vertices in the subsequent 
call to polygonjacc_3 (). 

Note: If the hue argument to set_shadiiig_parameters () is 0, then 
color_index_list is an index into the predefined colormap. If hue is 1, then the 
first 64 values in the predefined colormap are interpolated into color indexjist. 
If hue is 2, then the second 64 values are used, and so on. 

Set Z Buffer Cut set_zbuf fer_cut (surface_name, xlist, zlist, n) 

struct vwsurf *surface_name; /* See Appendix B */ 
float xlist[], zlist[]; 
int n; 

set_zbuf fer cut () specifies a cutaway view of 3D polygon objects when 
hidden surfaces are being removed. set_zbuf fer_cut () specifies an array 
of depths in NDC space. Any parts of objects which are closer to the viewer than 
this piecewise-linear function are clipped away. 

Note: this function has no effect on Graphics Processor view surfaces, i.e. 
gplddor gplpixwindd. x/wr is assumed to be monotonically increasing. 
This function specifies a piecewise-linear cutaway threshold in the z coordinate, 
which, given any X coordinate, is constant in y. The default cutaway depth is 0 
for all values of x. Values of x less than xlist [0] or greater than xlist [«- 1] will 
have the default depth. The view surface must have been initialized with the hid¬ 
den flag on. 

5.9. Polygon Functions The polygon functions are a SunCore extension to the ACM Core specification. 

(SunCore Extension) The polygon functions describe cormected sequences of lines which form closed 

figures. The polygons are filled in with color as specified by the 
set_f ill_index () primitive attribute, or are shaded according to the 
current shading parameters, depending on the polygoninterior_style 
primitive attribute. Only polygons created by the 3D polygon functions may be 
shaded. 
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The first two or three arguments to a polygon function are arrays of the appropri¬ 
ate coordinates. Consider the polygon function: 


o 


polygon_abs_3(x_array, y_array, z_array, n) 
float x_array[], y_array[], z_array[]; 

/* X, y, and z coordinates */ 
int n,- /* Number of coordinates */ 

The bounding sequence of edges that these arrays of coordinates describe pass 
from the first point x arrayfO],{y_array[0], z_array[0]), then mns through the 
intermediate array values to (x_array[n-1 ], y_array[n-1 ], z array[n-1 J) and then 
back to the first point, n is the numter of elements in each of the coordinate 
arrays. There are thus n sides in the figure described. 

Note that the polygon functions describe a closed figure. The last coordinate in 
the array of points is connected to the first point. 

o The number of coordinates, n, is less than or equal to two. 


□ There is no open segment. 


Describe Polygon in Absolute polygon_abs_2 (x array, y array, n) 

2D Coordinates float x_array[], y_array[]; /* x and y coordinates */ 

int n; /* number of array elements */ 

polygon_abs_2 () describes a polygon in absolute 2D world coordinates. 
The current position is set to the first point. 


Describe Polygon in Absolute polygon_abs_3 (x array, y array, z array, n) 

3D Coordinates float x_array[], y_array[], z_array[]; 

/* X, y, and z coordinates */ 
int n; /* number of array elements */ 

polygon_abs_3 0 describes a polygon in absolute 3D woild coordinates. 
The current position is set to the first point. 



Describe Polygon in Relative polygon_rel_2 (dx array, dy array, n) 

2D Coordinates float dx_array[], dy_array[] ; /* x and y deltas */ 

int n; /* number of array elements */ 

polygon_rel_2 () describes a polygon in relative 2D world coordinates. 
The first array value specifies a displacement firom the current position; remain¬ 
ing array values specify displacements from the preceding point The current 
position is set to the first point 


Describe Polygon in Relative 
3D Coordinates 


polygon_rel_3(dx_array, dy_array, dz_array, n) 
float dx_array[], dy_array[], dz_array[]; 

/* X, y, and z deltas */ 
int n; /* number of array elements */ 

polygon_rel_3 () describes a polygon in relative 3D world coordinates. 
The first array value specifies a displacement from the current position; remain¬ 
ing array values specify displacements from the preceding point The current 
position is set to the first point 
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5.10. Raster Primitive The raster primitive functions described in the following sections allow the Sun- 

Functions (SunCore Core application program to access and manipulate rectangular arrays of pixels. 

Extension) Both monochrome and color frame raster primitives are supported. These func¬ 

tions are not a part of the standard Core system. 

Raster Output Primitive put_raster (raster) 

struct suncore_raster *raster; 

put_raster () draws a rectangular 1-bit or 8-bit deep raster and enters it into 
the current segment. The raster may not be used in transformable segments, 
because rasters carmot be scaled or rotated in the current release of SunCore. A 
raster primitive may, however, be picked or dragged if it is entered in a translat¬ 
able segment. The current position is at the lower left-hand comer of the raster. 

Note that put_raster () is device dependent in that it is written to the right 
and upward from the current position a specified number of PIXELS in height and 
width. The current position is unchanged. 

Here is the definition of the suncore_raster stmcture. 

struct suncore_raster { 
int width; 
int height; 
int depth; 
short *bits; 

}; 

The depth parameter can be 1 or 8 bits per pixel. 

The bits of the raster are stored in the following order fotdepth = 1: The first 
word is the upper left 16 horizontal bits^ with the high order bit being the left¬ 
most bit The first (width +15)/16 words comprise die top row of the rectangle. 
The number of words of storage that bits points to is: 

((width+15) / 16) * height 

for depth =\. 

Rasters of rieptfe = 8 are stored as successive bytes in row order. The number of 
bytes that bits points to is: 

width * height 

for depth = 8. 

If a 1-bit deep raster is written to a color view surface, ‘0’ bits select the back¬ 
ground color and ‘1’ bits select the color specified by the fill index primitive attri¬ 
bute. 

Note that output clipping is always done on raster primitives. 
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get__raster (surf ace_name, xmin, xmax, 
ymin/ ymax, x, yr raster) 
struct vwsurf *surface__name; /* See Appendix B */ 
float xinin, ymin, xmax, ymax; 

/* Region of NDC space to read */ 
int X, y; /* starting point pixel offsets 
in raster relative top left */ 
struct suncore_raster ^raster; /* Returned Raster */ 

get_raster () reads a specified region of the monochrome or color frame 
buffer into a storage area. get_r aster () requires an area of memory large 
enough to hold the raster region that it returns. It is the user’s responsibility to 
allocate this storage area before calling get_raster (). The 
size_raster 0 and allocate_raster ( ) functions may be used to do 
this: 

size_raster {surface__naine, xmin^ xmax, ymin, ymax, ^raster) ; 
allocate_raster(&raster); 
if (raster.bits == NULL) 

error case - the raster could not be allocated 

else 

continue with the processing 

To free the area when finished with the raster, call the f ree_raster () func¬ 
tion: 

free_raster(&raster); 

Hence, a large raster may be allocated and then portions of it filled with data 
using get_raster () with various jc,.I y offsets, in pixel coordinates from the 
top left hand comer of the raster. 

Set Size of Raster in NDC size_raster(surface_name, xmin, xmax, ymin, ymax, raster) 

struct vwsurf *surface_name; 
float xmin, xmax, ymin, ymax; 
struct suncore_raster *raster; 

size_raster () returns the raster with the pixel coordinates widths height^ 
andrf^pf/i, for a specified region of NDC space and a specified view surface. On 
return, raster. bits is set to NULL. 

Allocate Space for a Raster allocate raster (raster) 

struct suncore_raster *raster; 

Given a raster whose widths height^ and depth fields were filled by the 
size_raster () function (described above), allocate_raster () allo¬ 
cates the memory required for that raster and sets the raster. bits pointer. 
allocate_raster 0 returns a NULL pointer value in raster .bits if it is 
unable to obtain enough memory for the raster stmcture. 

Free Space of a Raster f ree_raster (raster) 

struct suncore_raster ^raster; ^ 


Read Raster from 
Monochrome or Color Frame 
Buffer 
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Copy a Raster to a Disk 
Raster File 



free_raster () frees the memory used by a specified raster, if 
raster • bits is not NULL. 

raster_to_file (raster, map, fd, replicate) 
struct suncore_raster *raster; 
struct { 

int type; /* 1 for RGB color table */ 
int nbytes; /* 3 times number 
of color table elements */ 
char *data; /* ptr to nbytes/3 red, 
blue, and green bytes */ 

} *map; 

int fd; /^standard file descriptor for C programs */ 

/* FORTRAN logical unit number 
for FORTRAN programs */ 

/* Pascal file variable for Pascal programs */ 
int replicate; /* magnification factor */ 

raster_to_f ile () copies a raster to a disk file in Sun’s standard raster file 
format. If map. nbytes = 0, no color map data will be written. This would 
normally be the case for rasters copied from the bitmap display. 

The replicate parameter specifies whether the raster should be magnified on 
transmission to the file. The raster is transmitted without magnification if andr^- 
plicate^ 1, pixel-replication zoom for a factor of 2 magnification if repUcate= 2. 

Note: The colormap information provided to raster_to_f ile () includes 
integer color values in the range 0 - 255. SunCore normally takes floating point 
color values in the range 0-1.0. 

The format of the generated disk file can be found in the include file in 

<r as ter file. h>. Disk raster files can be printed on a raster addressable hard 

copy device by using the Ipr(l) command with the —v option. 


Get a Raster from a Disk File 



file_to_raster(fd, raster, map) 
int fd; 

/* standard file descriptor for C programs */ 

/* Fortran logical unit number for Fortran programs */ 
/* Pascal file variable for Pascal programs */ 
struct suncore_raster *raster; 
struct { 

int type; /* 1 for RGB color table */ 
int nbytes; /* 3 times number 
of color table elements */ 
char *data; /* ptr to nbytes/3 red, 
blue, and green bytes */ 

} *map; 

f ile_to_raster () allocates enough memory for a raster stored on a disk 
file, then fills in all fields of the raster and map structures. Note that this function 
frees map. data, unless data is NULL, and allocates map. data each time it is 
called — therefore map. data is only valid in the last call to this function. The 
raster • bits field is set to NULL if there is not enough room to allocate the 



Revision A, of 9 May 1988 


68 SunCore Reference Manual 


raster. 

The format of the disk file can be found in the include file in 
<rasterfile.h>. 



o 
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Attributes 


Attributes in SunCore specify general characteristics for segments and for output 
primitives. 

There are two major divisions of attributes. One set of attributes is called seg¬ 
ment attributes and applies only to retained segments. The other set is called 
primitive attributes and applies only to output primitives. There are no attributes 
which apply to both retained segments and to output primitives. 

Attributes are further subdivided into static and dynamic. Static attributes 
specify characteristics of retained segments or output primitives which apply for 
the entire lifetime of those objects. Dynamic attributes specify characteristics of 
segments which can change during the lifetime of those segments. Static primi¬ 
tive attributes are stored in the display list so that subsequent manipulation of a 
segment is performed with the appropriate attributes. 


6.1. Primitive Static 
Attributes 



The list below defines the primitive static attribute values. 
line index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for line and polyline output primi¬ 
tives. Index value 0 corresponds to the background color. For lines and 
polylines on monochrome displays, a non-zero line index gives black lines 
on a white backgroimd. SunCore initializes line index to 1. The range of 
possible values is 0 to 255. 

fill index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for polygon and taster output primi¬ 
tives. Index value 0 corresponds to the background color. For monochrome 
displays, the values form a set of definitions for texture, described later. 
SunCore initializes fill index to 1. The range of possible values is 0 to 255. 

text index 

is an index into three float arrays which determine the red, green, and 
blue components of the color displayed for markers and text Index value 0 
corresponds to the background color. For text and markers on monochrome 
displays, a non-zero texrindex" gives black on a white background. SunCore 
initializes text index to 1. The range of possible values is 0 to 255. 
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linestyle 

is an int value which controls the appearance of lines drawn. Linestyle can 
assume the values: 

SOLID Solid lines, 

DOTTED Dotted lines, 

DASHED Dashed lines, 

DOTDASHED 

Dotdashed lines. 

The definitions of these constants can be found in <usercore. h>. Sun- 
Core sets linestyle to SOLID at initialization time. 

polygon interior style 

is an int value which controls the interior filling style for polygons. 
polygon interior style can have the values: 

PLAIN Solid color polygon 

SHADED Shading style is set dynamically by 

set_shading_parameter s (). Only 3D polygons may be 
shaded. 


SunCore sets polygon interior style to PLAIN at initialization time. 
polygon edge style 

is iK)t implemented in the current release of SunCore. 
linewidth 

is a float value which describes, in world coordinates, the width of drawn 
lines. SunCore sets linewidth to 0.0 (the minimum) at initialization time. 


pen 


font 


is an int value which is passed to the device driver to select a particular 
device dependent pen. SunCore initializes pen to 0. 

is an int value which determines the character font in which text will be 
written. Font can assume the following values (for 
charprecision=CliARACTER): 

ROMAN If charprecision=STRJtiG, this gives a large raster font. 

GREEK If charprecision=STRJNG, this gives the default raster font. 

SCRIPT If charprecision=STRlNG, this gives a small raster font. 

OLDENGLISH If charprecision=STRJNG, this is equivalent to a bold ver¬ 
sion of GREEK. 

STICK If charprecision=STRING, this is equivalent to a medium 

sized ROMAN raster font. 

SYMBOLS Currently holds some electronics symbols (character values 
32 through 47). If charprecision=STRSNG, this is 
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equivalent to a bold version of STICK. 

SunCore sets/ont to STICK at initialization time. 
charsize 

is a pair of float values which determine the size of characters, in world 
coordinates. SunCore sets the default character width to 11.0 and the default 
character height to 11.0 at initialization time. 

charup 

attribute consists of three float values which represent a vector giving the 
direction of ‘up’ for "characters: 

(dx_charup, dy_charup, dz_charup) 

in world coordinates. Usually, charup is normal to charpath. SunCore 
establishes the default as a vector in die positive y direction (0.0,1.0,0.0) at 
initialization time. 

charpath 

consists of three float values which represent a vector: 

(dx_charpath, dy_charpath, dz_charpath) 

that determines the direction, in world coordinates, in which character 
strings will extend. SunCore sets the charpath attribute to (1.0,0.0,0.0) at 
initialization time. 

charspace 

is a single float value specifying die space, in world coordinates, which 
should be inserted between characters in a text string. SunCore establishes 
charspace with the value 0.0 at initialization time. 

charjust 

is not implemented in the current release of SunCore. 
charprecision 

is an int value which controls the quality of the text drawing operation. 
Charprecision can have tte values: 

STRING Fast raster fonts, fixed size, and fixed orientation. 

CHARACTER Hershey vector fonts. 
marker symbol 

determines the character which is plotted on the displays by the marker and 
polymarker functions described in Chapter 5. Any printable ASCII character 
can be used as the marker character. 

Note: The ACM Core specifies that the integer values 1 through 5 represent 
specific characters. SunCore does not implement this feature. 

pick id 

is an int value identifying the next output primitive. The input primitives 
use this number for user interaction with segments and primitives within 
segments. 
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O 

rasterop 

specifies the rasterop used when writing to the display. It can be one of: 

NORMAL Source value is written to the display. 

XORROP Source value is exclusive or’ed with the value already in the 
display before being written to the display. 

ORROP Source value is or’ed with the value already in the display 
before being written to the display. 

This attribute is ignored if set_drag () was specified as TRUE. 

The functions listed in the subsections below each set the specified attribute 
value for the indicated primitive attribute. 

□ One or more of the attribute values is incorrect. 

□ No character orientation can be established because dx charpath, 
dy_charpath, and dz charpath are all zero. 

□ No character up direction can be established because dx_charup, dy champ, 
and dz charup are all zero. 


6.2. Using Texture for 

Color Attributes on the 
Monochrome Display 


When a monochrome display is used, the fill index attribute is used to determine 
how a region of the screen is textured when using the polygon output primitives. 
Texturing is done in terms of 16 x 16 pixel regions of the screen. There are 16 
rows of 16 pixels each. The fill index attribute selects an entry from each of three 
arrays of float values in the range 0.0 through 1.0, representing red, green, and 
blue. In the case of the monochrome display, each of these three float 
numbers is converted to an integer between 0 and 255. Each of the 8-bit 
numbers is divided into two four-bit quantities, which we can call A and B. 



Table 6-1 Structure of a Fill-Index Value 


Red 

Green 

Blue 

Select Select 

B A 

Length Length 

B A 

Rotate Rotate 
B A 


Select A and Select B are four-bit values which are used to select an A pattern 
and a B pattern out of the table of numbers shown below. 
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Table 6-2 Texture Selection Values 




Four-Bit Value 

Hexadecimal Pattern 

Binary Pattern 

0 

0000 

0000000000000000 

1 

8000 

1000000000000000 

2 

8080 

1000000010000000 

3 

8410 

1000010000010000 

4 

8888 

1000100010001000 

5 

9124 

1001000100100100 

6 

9494 

1001010010010100 

7 

A552 

1010010101010010 

8 

AAAA 

1010101010101010 

9 

EB6E 

1110101101101110 

10 

DDDD 

1101110111011101 

11 

F7F7 

1111011111110111 

12 

FFFF 

1111111111111111 

13 

E3E3 

1110001111100011 

14 

FFOO 

1111111100000000 

15 

OOFF 

0000000011111111 


The patterns are then laid down in the texture field, pixels, as described in the 
pseudo code below. 

let X = y = Pattern A 
for index = 0 to Length A - 1 
pixels[index] = x | y 

if Rotate A & 1 then rotate x one bit right 

if Rotate A & 2 then rotate x one bit left 

if Rotate A & 4 then rotate y one bit right 

if Rotate A & 8 then rotate y one bit left 

let X = y = Pattern B 

for index = Length A to Length A + Length B - 1 
pixels[index] = x | y 

if Rotate B & 1 then rotate x one bit right 

if Rotate B & 2 then rotate x one bit left 

if Rotate B & 4 then rotate y one bit right 

if Rotate B & 8 then rotate y one bit left 

If the value of 

length A + length B 

is less than 16, the processes described above are repeated as many times as 
required to fill the 16 line region. 

The above encoding provides for an enormous number of textures. Here are a 
few of the useful ones. 
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Table 6-3 Useful Texture Selection Values 


Texture 

Red 

Green 

Blue 

Hatched Left 

0.1334 

0.5020 

0.3529 

Hatched Right 

0.1334 

0.5020 

0.6471 

Wallpaper 

0.4667 

0.5334 

0.2118 

Black 

0.0000 

0.2667 

0.3882 

White 

0.2667 

0.4001 

0.8001 

Wavy Lines 

0.3334 

0.4001 

0.1334 

Grey Tone 

0.5334 

0.4001 

0.5334 

Cross Hatched 

0.5334 

0.4001 

0.1334 




Assign Colors to Indices 


define_color_indices (surface_name^ ± 2 , 

red_arrayf green__array/ blue__array) 
struct vwsurf *surface_name; /* See appendix B */ 
int i2; /* indices range from 0 through 255 */ 
float red_array [ ], green_array [ ], blue__array [ ]; 


def ine_color_indices () defines entries in the color lookup table of a 
view surface. The three arrays provide the values for red, green, and blue respec¬ 
tively. The value of each element in the color arrays is in the range 0.0 through 
1.0. The function defines all the indices in the color index table between il and 
i2 inclusive, using the first 1241+1 elements from each of the three arrays. 

Subsequent calls to the set^xxx^index () function selects a color from the 
lookup table to use as a color attribute. 




Location 0 in the color tables is the background color for the view surface. For 
the monochrome displays, lines, text, and markers are drawn black for any color 
index other than 0. 

SunCore initializes the lookup table for monochrome view surfaces such that for 
the ith entry, red[i] - i, green[j] = 255—i, and blue[i] = i. SunCore iiutializes 
color view surfaces which have a full 256-element lookup table such that entry 0 
is gray, entry 1 is black, entries 2 through 63 contain an intensity ramp in red, 
entries 64 through 127 contain an intensity ramp in green, entries 128 through 
191 contain an intensity ramp in blue, and entries 192 through 255 contain an 
intensity ramp in yellow (ted+green). See appendix B for details of color view 
surfaces with fewer than 256 entries in the lookup table. 

Note: If the SunCore application is mn in the SunView environment, 
vwsurf. cmapname and vwsurf. cmapsize must be defined in order to 
cooperate with colormap sharing provided by SunView. 


Select a Line Color Attribute set_line_index (index) 

int index; /* range 0 through 255 */ 


set_line_index () selects a color by providing an index into the tables 
defined by the def ine_color_indices () function. This color attribute is 
applied to subsequent line and polyline output primitives. 
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Select a Polygon and Raster set_f ill_index (index) 

Color int index; /* range 0 through 255 */ 

set_f ill_index () selects a color by providing an index into the tables 
defined by the define_color_indices () fimction. This color attribute is 
applied to subsequent polygon and raster output primitives. 


Select a Text and Marker 
Color 


Set Linewidth 


v' ^ 


Set Linestyle 


set_text_index(index) 

int index; /* range 0 through 255 */ 

set_text_index () selects a color by providing an index into the tables 
defined by the def ine_color_indices () function. This color athibute is 
applied to subsequent text and marker output primitives. 

set_linewidth(linewidth) 
float linewidth; /* unit of width 
is 1 percent of NDC space */ 

set_linewidth () specifies the linewidth attribute for the output primitives. 
SunCore initializes linewidth to 0.0, which results in a one pixel wide line. 

If XOR’ing is enabled (via the set_rasterop () or set_drag () func¬ 
tions), lines whose pixel width is greater than one may partially overwrite them¬ 
selves, resulting in poorly drawn wide lines. Redrawing the lines with XOR’ing 
off will draw the lines correctly (until this problem is fixed). 

set_linestyle(linestyle) 

int linestyle; /* SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 

set_linestyle () specifies the linestyle attribute for output primitives. Sun- 
Core initializes linestyle to SOLID. 


Select Plain or Shaded 
Polygons 


Set Polygon Edge Style (No 
Effect) 


Set Font 



set_polygon_interior_style(style) 
int style; /* PLAIN, SHADED */ 

set_j)olygon_interior_style () specifies the method of filling for 
polygons. If the filling method is SHADED, polygons are shaded according to the 
parameters set by the set_shading_parameters () function. Only 3D 
polygons may be shaded. 

set_polygon_edge_style(style) 
int style; /* SOLID, INTERIOR */ 

set_polygon_edge_style () specifies the method of drawing the edges of 
a polygon. This function has no effect in the current release of SunCore. 

set_font(font) 

int font; /* ROMAN, GREEK, SCRIPT */ 

/* OLDENGLISH, STICK, SYMBOLS */ 

set_f ont () specifies the font attribute for the output primitives. SunCore ini¬ 
tializes font to STICK. If the charprecision attribute is set to STRING, ROMAN 
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gives a small Roman font, GREEK gives a stick figure font, SCRIPT gives a tiny 
stick figure font, OLDENGUSH gives a bold version of GREEK, SUCK gives a 
medium sized ROMAN raster font, and SYMBOLS gives a bold version of SUCK. 
The STRING precision fonts are ‘raster’ fonts and are not scalable or rotatable, 
hence they are in pixel coordinates and are larger on the color surface than on the 
monochrome bitmap display. 

Select a Device Dependent Pen set_pen (pen) 

(no effect) int pen; 

This function has no effect on the standard SunCore view surfaces. 

Set Character Size set_charsize (charwidth, charheight) 

float charwidth, charheight; 

set_charsize () specifies the charsize attribute for ihe text output primitive, 
in world coordinates. If the charprecision attribute is set to STRING, 
set_char size () has no effect, except to control the target extent of the text 
for the await_pick () function. If the charprecision attribute is set to CHAR¬ 
ACTER, set_charsize () sets the average size of a character, given that each 
character has its own size. 

Define Character Spacing for set_charspace (charspace) 

float charspace; 

set_charspace () specifies the space attribute for the text output primitive, 
in world coordinates. It is used to insert additional space between characters in 
text strings. If the charprecision attribute is set to STRING, 
set_charspace 0 has no effect. 

set_charup_2(dx, dy) 
float dx, dy; 

set_charup_2 () specifies the charup attribute for the text output primitive, 
in world coordinates. Note that the dz offset is set to 0.0 for this functiort If the 
charprecision attribute is set to STRING, set_charup_2 () has no effect; oth¬ 
erwise it specifies the upward direction for the characters. This provides for 
slanting, mirror imaging, and so on, for characters. 

set_charup_3(dx, dy, dz) 
float dx, dy, dz; 

set_charup_3 () specifies the charup attribute for the text output primitive, 
in world coordinates. If the charprecision attribute is set to STRING, 
set_charup_3 () has no effect; otherwise it specifies the direction of upward 
for the characters. This provides for slanting, mirror imaging and such, for char¬ 
acters. 

Set Character Path 2 set_charpath_2(dx, dy) 

float dx, dy; 

set_charpath_2 () specifies the charpath attribute for the text output 


Output Primitives 


Set Character Up Vector 2 


Set Character Up Vector 3 
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primitive, in world coordinates. Note that the dz offset is set to 0.0 for this func¬ 
tion. If the charprecision attribute is set to STRING, set_charpath_2 () has 
no effect; otherwise the character string is written in this direction. 

Set Character Path 3 set_charpath_3 (dx, dy, dz) 

float dx, dy, dz; 

set_charpath_3 () specifies the charpath attribute for the text output primi¬ 
tive, in world coordinates. If the charprecision attribute is set to STRING, 
set_charpath_3 () has no effect; otherwise the character string is written in 
this direction. 

Specify Text Justification (No set_char just (just) 

Effect) int just; 

set_char just () specifies how text strings should be justified. This function 
has no effect in the current release of SunCore. 


set_charprecision(charprecision) 
int charprecision; /* STRING, CHARACTER */ 

set_charprecision ( ) selects the method of drawing text. 

STRING Specifies characters of fixed size and orientation, which are 

drawn rapidly using raster operations. This is the default. 

CHARACTER Specifies Hershey vector fonts, which can be clipped and 
transformed. 

Set Marker Symbol set_marker_syinbol (marker) 

int marker; /* Character to use as Marker - 32 .. 127 */ 

set_marker_SYitibol () establishes the marker symbol primitive attribute. 
The character specified by the marker argument in the 
set_marker_syinbol () function call is subsequently used as the marker 
character by the marker and polymarker functions. 

Set Pick ID set_pick_id (pick_id) 

int pick_id; 

set_pick_id () specifies the pick id attribute for output primitives. The pick 
id attribute is only used by the await_pick input function. Subsequent output 
primitives are identified by the specified pick id when they are detected by the 
mouse pointing device, via the await_pick () input function. 

Select Rasterop to Display set_rasterop (rop) 

Memory (SunCore Extension) int rop; /* XORROP, orrop, normal */ 

set_rast erop () selects Xor’ing or or’ing of primitives to display memory. 


Set Character Precision 
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Specify All Primitive 
Attributes 


set_primitive_attributes () is a composite function which provides a 
means to set all the primitive attributes in a single function call. Note that the 
function call: 

set_primitive_attributes(&PRIMATTS) 

sets all the primitive attributes to their default values. PRIMATTS is defined in 

<usercore.h>. 


set_primitive_attributes(attributes) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} *attributes; 


6.3, Inquiring Primitive The functions described in the sections that follow allow the user to inquire static 

Static Attribute Values attribute values of the SunCore primitives. 

i ^ 

o A 2D inquiry function was used when a 3D inquiry function should have been 
used to avoid loss of information. 

Inquire Color Indices inquire_color_indices (surface_name, il, 12, 

red__array, green__array, blue_array) 
struct vwsurf *surface__name; /* See appendix B */ 
int il, i2; /* Start and end table indices */ 

float red__array[]; /* Range is 0.0 thru 1.0 */ 

float green_array[]; /* Range is 0.0 thru 1.0 */ 

float blue_array[]; /* Range is 0.0 thru 1.0 */ 

inquire_color_indices () obtains the color lookup table for the specified 
view surface, surface _name is the name of the view surface for which the color 
lookup tables should be obtained. 

inquire_color__indices () takes entries from the color lookup tables, 
starting at index il (relative to zero) and ending at index i2. The color lookup 
tables for a given color are stored in 

array[0] through array[i2-il] 


Inquire Line Index 


inquire_line_index (index) 
int *index; 

inquir e_line_index () obtains the current color index for coloring line 
and polyline output primitives. 
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Inquire Fill Index 


Inquire Text Index 


Inquire Linewidth 


Inquire Linestyle 


Obtain Polygon Shading 
Method 


Inquire Polygon Edge Style 


Inquire Pen 


Inquire Font 


Inquire Character Size 


inquire_fill_index(index) 
int *index; 

inquire_f ill_index () obtains tire current color index for coloring 
polygon and raster output primitives. 

inquire_text_index(index) 
int *index; 

inquire_text_index () obtains the current color index for coloring marker 
and text output primitives. 

inquire_linewidth(linewidth) 
float *linewidth; 

inquire_linewidth () obtains the linewidth attribute, in percent of NDC 
space, for the output primitives. 

inquire_linestyle(linestyle) 

int *linestyle; /* SOLID, DOTTED, */ 

/* DASHED, DOTDASHED */ 

inquire_linestyle ( ) obtains the linestyle attribute for the output primi¬ 
tives. 

inquire_polygon_interior_style(style) 
int *style; /* PLAIN, SHADED */ 

inquire_jpolygon_interior_style () obtains the method of filling for 
polygons. 

inquirejolygon_edge_style (style) 
int *style; /* SOLID, INTERIOR */ 

inquire_polygon_edge_style () obtains the current method of drawing 
polygon edges. 

inquire_pen(pen) 

int *pen; /* Device dependent pen selector */ 
inquire_j)en () obtains the pen attribute for the text output primitive. 

inquire_font(font) 

int *font; /* ROMAN, GREEK, SCRIPT, OLDENGLISH, */ 

/* STICK, SYMBOLS */ 

inquire_f ont () obtains theattribute for the text output primitive. 

inquire_charsize(charwidth, charheight) 
float *charwidth, *charheight; 

inquire_charsize () obtains the charsize attribute for the text output prim¬ 
itive. 
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Inquire Character Spacing 


Inquire Character Up 
Vector 2 


w 

inquire_charspace(charspace) 
float *charspace; 

inquire_char space () obtains the charspace attribute for the text output 
primitive. 

inquire_cha rup_2(dx ^ dy) 
float *dx^ *dy; 

inquire_charup_2 () obtains the charup attribute for the text output primi¬ 
tive. 


Inquire Character Up 
Vector 3 


Inquire Character Path 2 


Inquire Character Path 3 


inquire_charup__3 (dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_charup_3 () obtains the charup attribute for the text output primi¬ 
tive. 

inc[uire_charpath_2 (dx^ dy) 
float *dx, *dy; 

inquir e_charpath_2 () obtains the charpath attribute for the text output 
primitive. 

inquire_charpath_3(dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_charpath_3 () obtains the charpath attribute for the text output 
primitive. 



Obtain Justification Attribute inquire_char just (just) 

int *just; 

inquire_char just () obtains the justification attribute for text strings. 


Obtain Current Rasterop inquire rasterop (rop) 

(SunCoreExtension) *rop; /* xorrop, orrop, normal */ 

inquire_rasterop () determines the current setting of the rasterop attri¬ 
bute. 


Inquire Character Precision inquire_charprecision (charprecision) 

int *charprecision; /* STRING, CHARACTER */ 

inquire_charprecision () obtains the charprecision attribute for the text 
output primitive. 


Inquire Pick ID inquire_j)ick_id (pick_id) 

int *pick_id; 

inquire_pick_id () obtains the pick id attribute for output primitives. 




Revision A, of 9 May 1988 





Chapter 6 — Attributes 85 



\ 


Inquire Marker Symbol 


Obtain Ail Primitive 
Attributes 


6.4. Retained Segment 
V Static Attributes 


Set Image Transformation 
i Type 


inc[uire_inarker_syitibol (symbol) 
int *symbol; /* 32 .. 127 */ 

inquire_marker_symbol () obtains the current value of the marker sym¬ 
bol. 


inquirej>rimitive_attributes(attributes) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl^ polylinestyl, polyedgestyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chquality; 

int marker, pickid, rasterop; 

} *attributes; 

inquire_j>rimitive_attributes () is a composite function which pro¬ 
vides a means to obtain all the primitive attributes in a single function call. 


There is only one static attribute for segments. This is the image transformation 

type attribute. This attribute can take on one of five values: 

NONE Retained segment on which no translation, scaling, or rotation can be 
performed. 

XLATE2 Translatable retained segment. The segment can be moved 
(translated) in 2D (x and y of NDC space). 

XFORM2 Fully transformable retained segment. The segment can be moved 
(translated), rotated, and scaled (have its size changed) in 2D (x and 
y of NDC space). 


XLATE3 Translatable retained segment. The segment can be moved 
(translated) in 3D (x and y of NDC space). 

XFORM3 Fully transformable retained segment. The segment can be moved 
(translated), rotated, and scaled (have its size changed) in 3D (jc, y 
and ^ of NDC space). 

The image tranrformation type attribute is set when a segment is created and can¬ 
not be changed at any time during the life of the segment. The default value of 
image transformation type is NONE. 

The functions described below are used to set and inquire about the values of 
image transformation type. 


set_image_t rans f o rmat ion__type (type) 

int type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 
set_image_transf ormation_type () specifies the image 
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Inquire Image 
Transformation Type 


Inquire Segment Image 
Transformation Type 


6.5. Setting Retained 
Segment Dynamic 
Attributes 


I 

{ :] i 

transformation type attribute for subsequently created segments. 

inquire_image_transformation_type(type) 
int *type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

inquire_image_transf ormat ion_type () obtains the current value of 
the image transformation type attribute. 

inquire_segment_image_transformation_type(seginent_name, type) 
int segment_name; /* Name of segment for inquiry */ 
int *type; /* NONE, XLATE2, XFORM2, XLATE3, XFORM3 */ 

inquire_segment_image_transf ormation_type () obtains the 
image transformation type for a specified segment. 

In addition to the one static attribute described above, there are a number of 
dynamic attributes which apply to segments. Each retained segment has its own 
set of dynamic attributes, as listed below. 

Visibility 

indicates whether the segment should have a visible image. There are only 
two values of this attribute, namely: TRUE and FALSE. 

SunCore sets visibility to TRUE at initialization time. 

Highlighting 

indicates whether the segment’s image should be highlighted. In SunCore, 
highlighting is done by briefly blinking the segment. There are only two 
values of the highlighting attribute, namely, TRUE and FALSE. 

SunCore sets highlighted to FALSE at initialization time. 

Detectability 

indicates whether the retained segment can be detected by the 
await_pick () input primitive. A value of 0 means that the segment is 
not pickable. If two segments overlap, the one with the greatest value of 
detectability is the one that gets picked. SunCore sets detectability to the 
default value of 0 at initialization time. 

Image Tranrformation 

indicates how the image of a retained segment is scaled, rotated, or 
translated. Image transformations are done in NDC space, that is, after all 
viewing operations have been performed. Image transformations do not 
compose and do not cumulate. Whenever any function affecting a segment’s 
image transformation is called, the transformation is reset to reflect only the 
values specified by the call. The image U'onsformation attribute of a seg¬ 
ment must be consistent with its image transformation type attribute (for 
instance, if the image transformation type is XLATE2, it is an error to 
attempt to rotate the segment). 

SunCore sets the default image tranrformation to the identity transformation 
(that is, no translation, scaling, or rotation) at initialization. 



o 
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Set Visibility 


Set Highlighting 


Set Detectability 



Set Image Translate 2 


There are two classes of functions for setting retained segment dynamic attri¬ 
butes. One class sets the default attributes for subsequendy created segments; the 
other sets attributes on a named segment basis. 

o There is no retained segment called segment_name. 

o One or more of the attributes is incorrect. 

o The segment’s image transformation type attribute value is incompatible with 
the requested function. 

set_visibility(visibility) 

int visibility; /* TRUE or FALSE */ 

set_visibility () specifies the default visibility attribute for subsequently 
created segments. This does not affect the visibility of existing segments or the 
currentiy open segment. 

set_highlighting(highlighting) 

int highlighting; /* TRUE or FALSE */ 

set_highlighting () specifies the default highlighting attribute for subse¬ 
quently created segments. 

set_detectability(detectability) 

int detectability; /* 0 thru 2 to the 31rd power */ 

set_detectability () specifies the default detectability attribute for subse¬ 
quently created segments. 

set_iinage_translate_2 (tx, ty) 

float tx, ty; /* x and y translation values in NDC */ 

set_image_translate_2 () sets the default image transformation attribute 
for subsequendy created segments. The default image transformation is set to a 
2D translate by tx and ty. 


Set Image Transformation 2 



set_image_transformation_2(sx, sy, a, tx, ty) 
float sx, sy; /* x and y scale factors */ 
float a; /* rotation value in radians 

counter-clockwise about z axis */ 
float tx, ty; /* x and y translation values in NDC */ 

set_image_transf ormation_2 () sets the default image transformation 
for subsequendy created segments. The default transformation is set to a 2D 
scale by sx and sy, rotation by a, and translation by tx and ty. The order of 
transformation is: 

1. Sca/e about die origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rota¬ 
tion of 711/2 radians will rotate the x axis into the y aids. 

3. Translate. 
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To scale and rotate about a point x, y, add dxto tx and add dy to ty, where 
dx=x—(x^sx*cos (a )-y*sy*sin (a )) 



dx=y—(x*sx*sin (a }+y*sy*cos {a )) 


Set Image Translate 3 set_image_translate_3 (tx, ty, tz) 

float tx, ty, tz; /* x, y, and z Translation Values in NDC */ 

set_image_translate_3 () sets die default image transformation attri¬ 
bute, in NDC space, for subsequently created segments. The default image 
transformation is set to a 3D translate by tx, ty and tz. 


Set Image Transformation 3 


set_image_transformation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
float sx, sy, sz; /* x, y, and z Scale Factors */ 
float ax, ay, az; /* Rotation Values in radians clockwise */ 
/* about the x, y, and z axes */ 
float tx, ty, tz; /* X/ y, and z Translation Values in NDC */ 


set_image_transformation_3 () sets the default image transformation 
attribute for subsequently created segments. The default image transformation is 
set to a 3D scale by sx, sy, sz, a 3D rotation by ax ay, az, and a 3D translation by 
tx, ty, tz. The order of transformation is: 

1. Scale about (0.0,0.0,0.0) in NDC space, 

2. Rotate about (0.0,0.0,0.0) in NDC space, first about the r-axis, then about 
the y-axis, and then about the z-axis. Since NDC space is a left-handed coor¬ 
dinate system, rotations are computed using the left-hand rule. When the ori¬ 
gin is viewed from the positive side of the axis of rotation, clockwise rota¬ 
tions correspond to positive rotations. 


o, 


3. Translate. 


Set Segment Visibility set_segment_visibility ( segnient_naine,r visibility) 

int seginent_naine; 

int visibility; /* TRUE or FALSE */ 

set_segment_visibility () specifies the visibility attribute for the 
named segment. When visibility is set to FALSE, the segment is erased from the 
view surfaces. The segment is redrawn again when visibility is set to TRUE. 

Set Segment Highlighting set_seginent_highlighting (seginent_name, highlighting) 

int seginent__naine; 

int highlighting; /* TRUE or FALSE */ 

set_seginent_highlighting () specifies the highlighting attribute for the 
named segment. When highlighting is set to TRUE, the segment is blinked once. 
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Set Segment Detectability 


Set Segment Image 
Translate 2 


Set Segment Image 
Transformation 2 


set_segment_detectability (segment_naine, detectability) 
int segment_name; 

int detectability; /* 0 thru 2 to the 31rd power */ 

set__seginent_detectability () specifies the detectability attribute for 
the named segment. When detectability is ^t to 0, the segment cannot be picked 
by the await_j>ick () input function. If two segments overlap, the segment 
with the greatest detectability is picked. 

set_seginent__imagej^translate_2 (segment_name;^ tx, ty) 
int segment^name; 

float tx; /* X Translation Value in NDC */ 
float ty; /* y Translation Value in NDC */ 

set_segtnent_image_translate_2 () sets the image transformation 
attribute for the named segment. The image transformation is set to a 2D 
translate by tr, ty. The named segment is erased from the view surface and then 
redrawn after the new image transformation is applied. This may be done while 
the segment is open. 

set_segment_image_transformation__2 (segment_name , 
sXf 3Yf a, tx^ ty) 
int segment_name; 
float sx; /* X Scale Factor */ 

float sy; /* y Scale Factor */ 

float a; /* Rotation Value in radians 
clockwise about z axis */ 
float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

set__segment_image_transf ormation_2 () sets the image transforma¬ 
tion attribute for the named segment The image transformation is set to a 2D 
scale by sx and sy, a 2D rotation by a, and a 2D translation by tx and ty. The 
order of transformation is: 

1. Scale about the origin of NDC space. 

2. Rotate about the origin of NDC space (about the z axis). A positive rotation 
of Tdl radians will rotate the x axis into the y axis. 

3. Translate. 

To scale and rotate about a point x, y, add dxXotx and add dy to ty, where 
dr=jc-(jc*.yx* cos{a )-y*5y* sin(«)) 


dx=y-(jc*jjc* sin(a )+y*5y* cos(a)) 

The named segment is erased from the view surface and then redrawn after the 
new image transformation is applied. This may be done while the segment is 
open. 


Xr microsystams 
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Set Segment Image 
Translate 3 


Set Segment Image 
Transformation 3 


6.6. Inquiring Retained 
Segment Dynamic 
Attributes 


set_segment_iraage_translate_3 (segment^naine/ tx, ty, tz) 
int segment_naine; 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

set_segment_image_translate_3 () sets the image transformation 
attribute for the named segment. The image transformation is set to a 3D 
translate by tx^ ty, tz. The named segment is erased from the view surface and 
then redrawn after the new image transformation is applied. This may be done 
while the segment is open. 

set_seginent_image__transformation_3 (seginent_name , 
sx, sy, sz, ax, ay, az, tx, ty, tz) 
int segment__name; 
float sx; /* X Scale Factor */ 

float sy; /* y Scale Factor */ 

float sz; /* z Scale Factor */ 

float ax; /* Rotation Value in radians clockwise 
about the x axis */ 

float ay; /* Rotation Value in radians clockwise 
about the y axis */ 

float az; /* Rotation Value in radians clockwise 
about the z axis */ 

float tx; /* X Translation Value in NDC */ 

float ty; /* y Translation Value in NDC */ 

float tz; /* z Translation Value in NDC */ 

set_segment_image_transformation_3 () sets the image transforma¬ 
tion attribute for the named segment. The image transformation is set to a 3D 
scale by sx, sy, sz, a 3D rotation by ax, ay, az, and a 3D translation by tx, ty, tz. 
The order of transformation is: 

1. Scale about (0.0,0.0,0.0) in NDC space. 

2. Rotate about (0.0,0.0,0.0) in NDC space, first about the x-axis, then about 
the y-axis, and then about the z-axis. Since NDC space is a left-handed coor¬ 
dinate system, rotations are computed using the left-hand rule. When the ori¬ 
gin is viewed from the positive side of the axis of rotation, clockwise rota¬ 
tions correspond to positive rotations. 

3. Translate, 

The named segment is erased from the view surface and then redrawn after the 
new image transformation is applied. This may be done while the segment is 
open. 


The functions described below are for inquiring the settings of the dynamic attri¬ 
butes for retained segments. There are two classes of ftinctions for inquiring 
retained segment dynamic attributes. One class obtains the default attributes for 
subsequently created segments and the other obtains attributes on a named seg- 
ment basis. ^ / 
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Inquire Visibility 


Inquire Highlighting 


Inquire Detectability 


Inquire Image Translate 2 


Inquire Image 
Transformation 2 


Inquire Image Translate 3 


□ There is no segment called segment name. 

□ The default image transformation attribute value is of a more complex type 
than the inquiry function used. 

□ The segment’s image transformation type attribute value is incompatible with 
the requested function. 

□ The segment’s image transformation type attribute value is of a more complex 
type than the inquiry function used. 

inquire_visibility(visibility) 

int *visibility; /* TRUE,or FALSE */ 

inquire_visibility () obtains the default visibility attribute for subse¬ 
quently created segments. 

inquire_highlighting(highlighting) 
int *highlighting; /* TRUE or FALSE */ 

inquire_highlighting () obtains the default highlighting attribute for the 
subsequently created segments. 

inquire_detectability(detectability) 

int *detectability; /* 0 thru 2 to the 31rd power */ 

inquire_detectability () obtains the default detectability attribute for 
the subsequently created segments. 

inquire_image_translate_2 (tx, ty) 

float *tx, *ty; /* x and y Translation Values in NDC */ 

inquire_image_translate_2 () obtains the 2D translation components 
of the default image tramformation for subsequently created segments. 

inquire_iinage_transformation_2 (sx, sy, a, tx, ty) 
float *sx, *sy; /* x and y Scale Factors */ 
float *a; /* Rotation Value in radians 
cloclcwise about the z axis */ 
float *tx, *ty; /* x and y Translation Values in NDC */ 

inquire_image_transf ormation_2 () obtains the 2D scale factor, rota¬ 
tion, and translation components of the default image transformation attribute for 
subsequently created segments. 

inquire_iraage_translate_3(tx, ty, tz) 

float *tx, *ty, *tz; /* x, y, and z Translation Values in NDC 

inquire_image_translate_3 () obtains the 2D translation components 
of the default image transformation attribute for subsequently created segments. 
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Inquire Image 
Transformation 3 


Inquire Segment Visibility 



inquire_image_transformation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
float *sx, *sy, *sz; /* x, y, and z Scale Factors */ 

float *ax, *ay, *az; /* Rotation Values in radians clockwise 

about the x, y, and z axes */ 

float *tx, *ty, *tz; /* x, y, and z Translation Values in NDC * 

inquire_image_transf ormation_3 {) obtains the 3D scale factor, rota¬ 
tion, and translation components of the default image transformation attribute for 
subsequently created segments. 


inquire_seginent_visibility {segment_name, visibility) 
int segment_name; 

int *visibility; /* TRUE or FALSE */ 

inquire_segment_visibility () obtains the visibility attribute for the 
named segment. 


Inquire Segment Highlighting 


Inquire Segment Detectability 


Inquire Segment Image 
Translate 2 


Inquire Segment Image 
Transformation 2 


inquire_segTOent_highlighting (segHient_naine, highlighting) 
int seginent_name; 

int *highlighting; /* TRUE or FALSE */ 

inquire_segment_highlighting () obtains the highlighting attribute 
for the named segment. 

inquire_segment_detectability(segment_name, detectability) 
int segment_name; 

int *detectability; /* 0 thru 2 to the 31rd power */ 

inquire_segment_detectability () obtains the detectability attribute 
for the named segment. 


O ' 


inquire_segment_iinage_translate_2 (seginent__name, tx, ty) 
int segment_name; 

float *tx; /* X Translation Value in NDC */ 
float *ty; /* y Translation Value in NDC */ 

inquire_segment_image_translate_2 () obtains the 2D translation 
components of the named segment’s image transformation attribute. 


inquire__segment__image_transf onnation_2 (segment_name, 
sx, sy, a, tx, ty) 
int segment_naine ; 
float *sx; /* X Scale Factor */ 

float *sy; /* y Scale Factor */ 

float *a; /* Rotation Value in radians clockwise 

about the z axis */ 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC */ 

inquire_seginent_image_transf ormation_2 () obtains the 2D scale 
factor, rotation, and translation components of the named segment’s image 
transformation attribute. ^ 
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Inquire Segment Image 
Translate 3 


Inquire Segment Image 
Transformation 3 


inquire_segment_image_translate_3 (seginent_name, tx, ty, tz) 
int segment_name; 

float *tx; /* X Translation Value in NDC */ 

float *ty; /* y Translation Value in NDC */ 

float *tz; /* z Translation Value in NDC */ 

inquire_segment_image_translate_3 () obtains the 3D translatioh 
components of the named segment’s image transformation attribute. 

inquire_seginent_image_transformation__3 (segment_name ^ 
sx, sy, sz^ ax, ay, az, tx, ty, tz) 
int segment_name; 


float 

*sx; 

/* X Scale Factor */ 

float 

*sy; 

/* y Scale Factor */ 

float 

*sz; 

/* z Scale Factor */ 

float 

*ax; 

/* Rotation Value in radians clockwise 
about the x axis */ 

float 

*ay; 

/* Rotation Value in radians clockwise 
about the y axis */ 

float 

*az; 

/* Rotation Value in radians clockwise 
about the z axis */ 

float 

*tx; 

/* X Translation Value in NDC */ 

float 

*ty; 

/* y Translation Value in NDC */ 

float 

*tz; 

/* z Translation Value in NDC */ 


inquire_segment_image_transf ormation__3 () obtains the 3D scale 
factor, rotation, and translation components of the named segment’s image 
transformation attribute. 
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Input Primitives 


SunCore supports several logical input devices providing for interactive use of 
the graphics system. The physical input devices provided are the keyboard and 
the mouse. The mouse is versatile in that it can be used both as a pointer and a 
button device. 

In the terminology of the ACM Core specification, input devices fall into two dis¬ 
tinct classes, namely: devices that generate events, and devices fiiat may only be 
sampled for position or numerical values. SunCore supports the ACM Core stan¬ 
dard level 2 input (synchronous); hence no event generation or event queue is 
supported. The supported logical devices in SunCore are: 

Table 7-1 Input Devices Supported By SunCore 


Device 

Descruption 

PICK 

identifies a segment or a primitive within a seg¬ 
ment. SunCore uses the mouse as a PICK dev¬ 
ice. 

KEYBOARD 

provides alphanumeric information to the appli¬ 
cation program. 

BUTTON 

provides a means of choosing among several 
alternatives. In SunCore, the three BUTTON 
devices are on the mouse. 

STROKE 

generates a sequence of positions in NDC space. 

In SunCore, the STROKE device is the mouse. 

LOCATOR 

provides a position in NDC space. SunCore uses 
the mouse as the LOCATOR device. 

VALUATOR 

provides a scalar value to the application pro¬ 
gram which samples it. SunCore uses the mouse 
as the valuator device. 


A logical input device must be initialized before it can be used. 


Initializing and The functions described in the sections that follow are used to initialize and ter- 

Terminating Input minate input devices. These functions are normally called at the begiiming and 

Devices end of a SunCore application program. 
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Initialize a Specific Device initialize_device (device_class, device_nuinber) 

int device_class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_number; /* There are; */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

initialize_device 0 initializes a specific logical device. This function 
must be called before accessing any of the input devices. An initialized input 
device which uses position infonnation from the mouse must be associated with 
an initialized view surface (as an echo surface) before valid data can be read from 
the device. See Appendix B for details. 

Note: that if the KEYBOARD device is initialized and the program crashes before 
the KEYBOARD device is terminated, the tty will not echo and cbreak will be set. 
To recover from this condition, type ‘reset’ followed by a carriage return. 

o The device specified by device jtumber is not initialized. 

o The device specified by device number is already initialized. 

Disable a Specific Device terminate_device(device_class, device_nuinber) 

int device_class; /* PICK, KEYBOARD, STROKE */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device_nuinber; /* There are: */ 

/* 1 PICK device */ 

/* 1 KEYBOARD device */ 

/* 1 STROKE device */ 

/* 3 BUTTON devices */ 

/* 1 LOCATOR device */ 

/* 1 VALUATOR device */ 

terminate_device () disables a specific device. 

□ The device specified by device jiumber is not enabled. 

7.2. Device Echoing Device echoing means that SunCore can provide a visible indication to the user 

that the system has seen the input from a specific input device. 

SunCore provides the means whereby the application programmer can control 
the way in which input devices are echoed to the user of the graphics system. 

Firstly, the types of echoing for each device are defined here. The tables below 
describe the types of echoing for specific devices. 
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Table 7-2 


Table 7-3 


Table 7-4 


Table 7-5 


Echoing for PICK Device 


Echo Type 

Actions Performed 

0 

No echo 

1 

SunCore blinks the picked segment briefly. A 
printer’s fist (pointing finger) indicates the 
position of the PICK device. 

2 

A printer’s fist (pointing finger) indicates die 
position of the PICK device. SunCore does 
not blink the picked segment. 

Echoing for KEYBOARD Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

The string which the user typed on the KEY¬ 
BOARD device is echoed on the screen start¬ 
ing at the echo reference position. 

Echoing for BUTTON Device 

Echo Type 

Actions Performed 

0 

No echo 

1 

No echo 

Echoing for STROKE Device 

Echo Type 

Actions Performed 


0 No echo 

1 a printers fist (pointing finger) sign is 
displayed at tlw cursor position. 

2 A string of dots is drawn to follow the path of 
the cursor, (not implemented) 

3 A solid line is drawn to follow the path of the 
cursor, (not implemented) 

4 a printers fist sign is displayed at the final 

_position of the cursor, (not implemented) 
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Table 7-6 Echoing for LOCATOR Device 



Echo Type 

Actions Performed 

0 

No echo 

1 

A printers fist (pointing finger) sign is 
displayed at the position of the LOCATOR 
device. 

2 

A solid line is drawn connecting the echo 
reference point with the LOCATOR. 

3 

A solid line is drawn connecting the echo 
reference point with the x coordinate of the 
LOCATOR. 

4 

A solid line is drawn connecting the echo 
reference point with the y coordinate of the 
LOCATOR. 

5 

A solid line is drawn connecting the echo 
reference point with either the x coordinate, or 
the y coordinate, of the LOCATOR, which¬ 
ever is farthest from the echo reference point 

6 

A box is drawn with the position of the 

LOCATOR as one comer, and the echo refer¬ 
ence point as the opposite comer. 


Table 7-7 Echoing for VALUATOR Device 


Echo Type 

Actions Performed 

0 

No echo 

1 

The current value of the valuator is displayed 
on the screen starting at the echo reference 
point 

2-11 

SunCore does not perform the actions as 
described in the ACM Core specification, 
which sets the values of the valuator into vari¬ 
ous parameters of the 
image_transformation_type attribute of 
retained segments. SunCore leaves this up to 
the application program. 


Define Type of Echo for set_echo (device_class/ device_number, echo_type) 

Device int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 

int device__number; 
int echo_type; 

set_echo () determines the echo type for a input device. 
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Define Type of Echo for a set_echo_group (device_class, device_nuinber_array, n, echo_type) 

Group of Devices device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_nuinber_array [] ; 
int n; /* number of devices in array */ 
int echo_type; 

set_echo_group () determines the echo type for an input device class. 

Define Echo Reference Point set_echo_position(device_class, device_nuinber, echo_x, echo_y) 

int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_nuinber; 

float echo_x; /* x Coordinate of Echo Point */ 

float echo_y; /* y Coordinate of Echo Point */ 

set_echo_position () specifies the position, in NDC space, which will be 
used as the echo reference point. The coordinates must lie within the bounds of 
NDC space, or set_echo_posit ion () will set the echo reference point to be 
the point in NDC space closest to the specified point. The echo reference point 
that diis function defines is used for certain types of echo such as rubber band 
LOCATOR echo. 

set_echo_surface{device_class, device_number, surface_name) 
int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_number; 

struct vwsurf *surface_name; /* See Appendix B */ 

set_echo_surf ace () specifies the viewing surface on which echoing will 
be done. An initialized input device which uses position information from the 
mouse must be associated with an initialized view surface (as an echo surface) 
before valid data can be read from the device. See Appendix B for details. If a 
NULL pointer is given for the surface jtame argument, any association of the 
specified input device with an echo surface is ended. 

7.3. Setting Input Device The functions described in the sections that follow are used to define certain 

Parameters parameters for each of the logical input devices. These functions are normally 

called at the begirming of a SunCore application program. 

Initialize LOCATOR Position set_locator_2 (locator_nuinber, x, y) 

int locator_nuinber; 
float x; 
float y; 

set_locator_2 () sets die initial LOCATOR position in NDC space. 



Define View Surface for Ek:ho 

( 
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Initialize Value and Range for set_valuator (valuator_nuinber, initial_value, low, high) 
VALUATOR Device int valuator__nuinber; 

float initial_value; 
float low; 
float high; 

set_valuator () sets the value and range for the valuator device. The 
default values are: initiallyalue =^0.0^ low^O.O, and high^l.O, 


Initialize KEYBOARD 
Parameters 


Initialize STROKE Device 


set_keyboard(keyboard^number, buffer_size, 
initial_string;. initial_cursoreposition) 
int keyboardeHumber; 
int buffereSize; 
char *initialeString; 
int initiale.cursor_position; 


set__i<^eyboar d () sets the size of the character buffer for the KEYBOARD 
device, the initial character string, and the initial character cursor counting from 
the echo reference position. SunCore uses default values of buffer_size=iO, 
initial string='Qntcr:'\ md initial cursor j>osition^l. The maximum 
buffereSize and the maximum length of initial stiing are 80 characters. 


set_stroke (stroke__nuinber, buf fer__sizer distance^- time) 
int stroke_niimber; /* Device Number */ 
int buffer_size; /* not used */ 

float distance; /* Minimum distance to move */ 

int time; /* not used */ 



set_st roke () sets parameters for the STROKE device. The bujfer_size 
argument is the maximum number of a:, y points in a STROKE. The distance 
argument is the minimum distance, in NDC space, which the mouse must move 
before a new point is added to the jc, y list comprising the STROKE. The default 
setting is distance=0,0L 


Initialize PICK Device 


7A Reading From Input 
Devices 


set_pick(pick-number, aperture) 

int pick-number; /* device number */ 

float aperture; /* device aperture */ 

set_pick () sets the aperture for the PICK device. The aperture argument 
provides control over the ‘sensitivity’ of the PICK device. A square is defined 
with its center at the cursor position and with sides of length 2 * aperture. Seg¬ 
ments that intersect this square can be picked, aperture is given in NDC space. 
An error is returned if the pick-number is incorrect or if the aperture <0.0. The 
default aperture square has two pixels per side. 


SunCore has several functions for interrogating input devices. These function 
allow the application programmer a great deal of flexibility in user-interface 
design. 
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Wait for BUTTON Device await_any_button(time, button_nuinber) 

int time; /* Time in microseconds to wait */ 
int *button_number; /* BUTTON which was hit */ 

await_any_button () waits for the user to click any of the BUTTON dev¬ 
ices. await_any_button () waits for the user to click any BUTTON device, 
or until the time specified by the time parameter expires. If the time argument is 
exactly zero, the BUTTON devices are checked once, then the function returns to 
the caller immediately. 

If a BUTTON device is clicked before time expires, the number of the BUTTON 
device is returned in the button number parameter. If the user does not click any 
BUTTON device before time expires, the function returns a BUTTON device 
number of zero. 

For the mouse, BUTTON device numbers 1, 2, and 3 represent the left, middle, 
and right buttons, respectively, when the buttons are facing away from the user. 

Wait for PICK Device await__pick (time, pick_number, segment_name, pick_id) 

int time; /* Time in microseconds to wait */ 
int pick_number; 
int *segment_name; 
int *pick_id; 

await_pick 0 waits for the user to pick an output primitive within a visible 
and detectable retained segment. await_pick () waits for the user to click the 
left hand button on the mouse, or until the time specified by the time parameter 
expires. If the time argument is exacdy zero, the function tests the button once, 
and if the button has been clicked, performs the pick operation. 

If the button is clicked before time expires, the function returns the 
segmentjtame of the segment that the PICK device is pointing at, and the 
pick id parameter is set to the value of the pick id attribute of the primitive that 
was picked. If the user does not click any mouse button before time expires, or 
no segment is found where the user points, the function sets the segment name 
andparameters to zero. 

await_pick () only searches those segments which are visible and detectable 
and appear on the echo surface of the specified PICK devic*. Primitives within a 
segment have bounded volume descriptors. The square pick aperture must inter¬ 
sect one of these ‘extents’ in order that the segment name and pick id be 
returr«d. If more than one segment is at the point, the segment with the highest 
value of the detectability attribute is returned. Detectability may be set to zero to 
prevent a segment from being picked. 

o The specified PICK device does not exist. 
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Wait for Input from the 
KEYBOARD 


Wait for User to Draw a 
Curve 


await_keyboard(time, keyboard_number, input_string, length) 

int time; /* Time in microseconds to wait */ 

int keyboard_number; 

char *input_string; 

int *length; 

await_keYboard () waits for the user to type a line of input on the KEY¬ 
BOARD device, awai t_keyboard () waits for the user to enter data at the 
KEYBOARD device, or until the time specified by the rime parameter expires. If 
the time argument is exactly zero, the function tests once to see if a character has 
been typed, and then returns to the caller. 

If any data is entered at the KEYBOARD device before tune expires, the function 
returns the typed characters in an array pointed to by input string. The length of 
this character string is returned in length. The string is null terminated. If the 
user does not enter any data before time expires, the function sets the length 
parameter to zero. If a carriage-return or newline character is typed, the function 
returns with the input string containing a newline character as the last non-null 
character. 

□ The specified KEYBOARD device does not exist. 


await_stroke_2(time, stroke_number, array_size, 
x_array, y_array, number_points) 
int time; /* Time in microseconds to wait */ 
int stroke_number; /* STROKE device to wait for */ 
int array_size; /* Maximum size of x and y arrays */ 
float x_array[]; 
float y_array[]; 

int *number_points; /* Number of x, y coordinates 
actually read */ 




await_stroke_2 () waits for the user to draw a curve, consisting of a list of 
points in NDC space, using the mouse. A curve in this context means a string of 
line segments. await_stroke_2 () waits for the user to draw a curve using 
the mouse, or until the time specified by the time parameter expires. If the time 
argument is exactly zero, the function tests once to see if a curve has been drawn, 
and then returns to the caller. 


The curve starts at the current position of the LCXTATOR, and finishes when the 
user clicks button 3 on the mouse. When the function returns, the number of x, y 
coordinates actually read is returned in the number_points argument When the 
number of points read equals array_size the function returns before time expires. 
Note: TIk BUTTON device must be initialized for await_stroke_2 () to 
work. 




Revision A, of 9 May 1988 





Chapter? — Input Primitives 105 


Read LOCATOR When 
BUTTON Clicked 


Read VALUATOR When 
BUTTON Clicked 


Low Level Mouse Support 
(SunCore extension) 


await_any_button_get_locator_2 (time, locator_nuinber, 
button_number, x, y) 

int time; /* Time in microseconds to wait */ 
int locator_number; /* LOCATOR device to wait for */ 
int *button_number; /* BUTTON which was clicked */ 
float *x, *y; /* Returned point in NDC */ 

await_any_button_get_locat or_2 () waits for the user to click any of 
the mouse buttons. When the button is clicked, the function returns the current 
NDC coordinates of the LOCATOR. 

await_any_button_get_locator_2 ( ) waits for the user to click any 
mouse button, or until the time specified by the time argument expires. If the 
time ailment is exacdy zero, the function checks if any buttons have been 
clicked immediately and then returns. 

If the time expires before the user has clicked any of the mouse buttons, the func¬ 
tion returns a zero in the button_number argument. 

await_any_button_get_valuator(time, valuator_number, 
button_number, value) 

int time; /* Time in microseconds to wait */ 
int valuator_number; /* VALUATOR number to read from */ 
int *button_number; /* BUTTON which was clicked */ 
float *value; /* Value of valuator */ 

await_any_button_get_valuator () waits for the user to click any of 
the mouse buttons, or for a specified time. When the button is clicked, the func¬ 
tion returns the current value of the valuator. 

await_any_button_get_valuator () waits for the user to click any 
mouse button, or until the time specified by the time argument expires. If the 
time argument is exacdy zero, the function checks if any buttons have been 
clicked and then returns immediately. 

If the user clicks one of the mouse buttons, the function returns with the value of 
the valuator, and the number of the button which was clicked. If the time expires 
before the user has clicked any of the mouse buttons, the function returns a zero 
in the button number argument. Movement of the mouse left or right lowers or 
raises the value of the valuator. Note: The BUTTON device must be initialized 
for await_any_button_get_valuator () to work. 

get_mouse_state(device_class, device_number, x, y, buttons) 
int device_class; /* PICK, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_number; 
float *x, *y; 
int *buttons; 

get_mouse_state () reads the low level mouse x, y and button information 
corresponding to a particular input device. The buttons are up-down encoded, 
and the location of the mouse is in NDC space. 
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Bit 0 of buttons is the right-hand mouse button. 

Bit 1 of buttons is the middle mouse button. 

Bit 2 of buttons is the left-hand mouse button. 

A zero bit means that the button is up, while a one bit means that the button is 
down. 




7.5. Inquiring Input Status 
Parameters 


The functions described in the sections that follow are used to inquire various 
parameters of the logical input devices. 


Obtain Type of Echo for inquire_echo{device_class, device_nuinber, echo_type) 

Device int device_class; /* PICK, KEYBOARD, STROKE, */ 

/* LOCATOR, VALUATOR, BUTTON */ 
int device_nuinber; 
int *echo_type; 

inquire_echo () obtains the echo type for the specified device. 


Obtain Echo Reference Point inquire_echo_position (device_class, device_nuniber, 

echo_x, echo_y) 
int device_class; 
int device_nuniber; 

float *echo_x; /* x Coordinate of Echo Point */ 

float *echo_y; /* y Coordinate of Echo Point */ 

inquire_echo_position () obtains the position, in NDC space, of the 
echo reference point for the specified device. 




Obtain View Surface for Echo inquire_echo_surface (device__class, device__numbery surface_name) 

int device_class; 

int device_number; 

struct vwsurf *surface_name; 

inquire_echo_surf ace () obtains the viewing surface on which echoing 
is done for the specified device. 


Obtain Initial LOCATOR inquire_locator_2 (locator__nuinber, x, y) 

Position irit locator_nuinber; 

float *x; 
float *y; 

inquire_locator_2 () obtains the initial position of the specified LOCA¬ 
TOR in NDC space. 


Obtain Value and Range for 
VALUATOR Device 


inquire_valuator (valuator__nuinber, initial__value, low, high) 
int valuator__nuinbere¬ 
float *initial_value; 
float *low; 
float *high; 

inquir e_valuator () obtains die value and range for the specified valuator f ) 
device. ^ 
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r- 

V_ Obtain KEYBOARD 
Parameters 


Obtain STROKE Device 
Parameters 


inquire__keyboard(keyboard__nuinber, buffer_size, initialustring, 
initial_cursor_j?osition) 
int keyboard^number; 
int *buffer_size; 
char *initial_string; 
int *initial_cursor_position; 

inquir e_keyboar d () obtains the size of the character buffer, the initial 
character string, and the initial character cursor for the specified KEYBOARD 
device. 

inquire__stroke (stroke__nuinber, buffer_size, distance^ time) 
int stroke__nuinber; /* device number */ 
int *buffer_size; /* not used */ 

float *distance; /* minimum distance to move in NDC */ 
int *time; /* not used */ 

inquire_stroke () obtains the buffer size, distance, and time parameters for 
the specified STROKE device. 
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Deviations from ACM SIGGRAPH 

Core 


This appendix points out specific differences between the SunCore grajMcs 
package and the ACM SIGGRAPH Core Specification. In addition to differences 
noted here, SunCore has numerous extensions to the ACM Core which are docu¬ 
mented in the main body of this manual. 


A.I. Unimplemented 
Functions 

Table A-1 



Here is a list of those functions which SunCore does not implement: 

Unimplemented Primitive Attribute Functions 

Primitive Attribute Functions 

set_char just 
inquire_charjust 


Table A-2 Unimplemented Synchronous Input Functions 


Synchronous Input Functions 

await stroke 3 

initialize group 

inquire button 

inquire__echo_segments 

inquire__input_capabilities 

inquire_input__device_characteristics 

inquire locator 3 

inquire_locator_dimension 

inquire_locport_2 

inquire_locport__3 

inquire_pick 

inquire_stroke_;_dimension 

set_all_buttons 

set_button 

set_echo segment 

set_locator_3 

set__locport__2 

s e t_l o cpo r t__3 

terminate_group 
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Table A-3 Unimplemented Asynchronous Input Functions 


Asynchronous Input Functions 

enable_device 

enable_group 

disable___device 

disable_group 

disable_all 

read_locator_2 

read__locator_3 

read__valuator 

await_event 

f lush_device_event s 

f lu sh_gr oup_e ve nt s 

flush all events 

associate 

disassociate 

disassociate_device 

disassociate_group 

disassociate_all 

ge t_pi ck__dat a 

get_keyboard_data 

get__stroke_data_2 

get_stroke_data_3 

get_locator_data_2 

ge t_l o ca t o r_dat a_3 

get valuator data 

inquire device associations 

inquire_device_status 


Table A-4 

Unimplemented Control Functions 



Control Functions 


inquire output capabilities 
set iiranediate visibility 
inquire control status 
log__error 

inquire_selected_surfaces 
make_jpicture_current 
set visibilities 

Table A-5 

Unimplemented Escape Functions 



Escape Functions 




escape 

inquire_escape 


A.2. Other Differences 


Text 


Raster Extensions 


The sections that follow describe other differences between die Core 
specification and SunCore. 

SunCore does not have the charplane primitive attribute; instead, the charpath, 
champ, and charspace attributes ate used to specify text orientation as described 
in the manual. The current release of SunCore has no STROKE precision text 
and no text justification. The inquire_text_extent_2 () and 
inquire_text_extent_3 () functions do not take a view surface name as 
an argument. The text inquiry functions only return meaningful values when die 
current charprecision attribute is CHARACTER. 


SunCore contains several of the proposed raster extensions to die ACM Core and 
other raster functions. Thus there are no color or intensity primitive attributes. 
Instead a color lookup table model is used. There are several primitive attributes 
which ate indices into lookup tables. In addition, hidden surfaces ate supported 
on color view surfaces. This requites a second parameter to the 
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Miscellaneous 


initialize_view_surf ace () function. 
SunCore adds these functions: 


Table A-6 SunCore Extensions 


_ SunCore Extension Functions 

s e t_image_t r a n s 1 at e_3 

inquire_image_translate_3 

set_segment_iinage_translate_3 


inquire 

_segment_image_translate_3 

Table A-7 SunCore Replacements 

Core Function 

SunCore Replacement 

set primitive attributes 2 
s e t r imi t i ve_a t tribute s_3 

set_primitive attributes 

inquire primitive attributes 2 
inquire primitive attributes 3 

inquire_primitive attributes 


Default values for many SunCore system parameters differ from those of the 
ACM Core. 

There are restrictions on set_wor ld_coordinat e_mat rix_2 () and 
set_world_coordinate_matrix_3 () as described in the manual. 

As described in the manual, some of the echo types for input functions in the 
ACM Cote are not implemented. 

The maricer symbol primitive attribute deviates from the ACM Cote as described 
in the manual. 

Batching of updates only applies to dynamic segment attributes as described in 
the manual. 

View surfaces initialized for hidden-surface elimination do not support dynamic 
segment attributes of highlighting, transformation, or translation, 
initial!ze_view_surf ace () can optionally suppress clearing the view 
surface when it is initialized. 
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SunCore View Surfaces 


B.l. The vwsurf 
Structure 



SunCore supports several types of view surfaces and multiple simultaneous 
instances of any type, subject to the hardware resources of the workstation on 
which a SunCore program is being run. The current release allows up to five 
view surfaces to be active at any time. This appendix gives implementation 
details of SunCore view surfaces and provides information on initializing them. 

View surface names in SunCore are structures. The following declaration and 
definitions are contained in the header file <usercore. h>: 

#define DEVNAMESIZE 20 

struct vwsurf { 

char screenname[DEVNAMESIZE]; 

char windowname[DEVNAMESIZE]; 

int windowfd; 

int (*dd)(); 

int instance; 

int cmapsize; 

char cmapname[DEVNAMESIZE]; 
int flags; 
char **ptr; 

} ; 


#define NULL_VWSURF 0, 0, 0, 0, 0, 0} 

#define DEFAULT_VWSURF(ddname) \ 

0, ddname, 0, 0, 0, 0} 

fdefine VWSURF_NEWFLG 1 

After initialization via the function initialize_view_surface (), a 
vwsurf stracture represents a specific instantiation of a particular type of view 
surface. The elements of the vwsurf structure completely characterize that 
instantiation and/or provide information used to initialize fhe view surface. This 
appendix refers to members of the vwsurf stmcture using the standard C nota¬ 
tion, as if the declaration 

struct vwsurf vwsurf; 

had been given. 

vwsurf.screenname 

is a character string which is the name of the physical device on which the 
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view surface appears (for example, IdevIcgoneO). 
vwsurf.windowname 

is a character string which is the name of a window device which has been 
opened for display of the output primitives directed to the view surface (for 
example, Idev/winlO). 

vwsurf.windowfd 

is the file descriptor corresponding to this device. Since, for all current Sun- 
Core view surface types, output display and input device echoing are accom¬ 
plished through window system functions, these members of the structure 
are valid even for raw output devices. 

vwsurf.dd 

is the name of the device-independent/device-dependent interface function 
through which graphics output to the view surface will pass. This function 
defines the view surface type. The current SunCore view surface types are 
described below. 

vwsurf.instance 

identifies the instantiation of a view surface type. It should be set to 0 prior 
to calling initialize_view_surf ace (). SunCore will set this value 
appropriately if the initialization is successful. 

vwsurf.cmapsize 

defines the size of the color lookup table for the view surface, and the char¬ 
acter string vwsurf.cmapname gives its name, which can be used to share a 
color map between two or more view surfaces on the same physical device. 
These elements of the vwsurf structure are used only for view surfaces on 
color devices. Their use is described more fully below. 

vwsurf.fligigs 

is a ffeld of one-bit flags. Currently, only one flag, VWSURF NEWFLG, is 
defined; this flag is described below. 

vwsurf.ptr 

is a pointer to an array of character pointers. The array should be terminated 
by a null pointer. The strings pointed to by the array contain optional infor¬ 
mation which may be used to initialize the view surface. Details are pro¬ 
vided below. 

B.2. View Surface Types A view surface type in SunCore is the name of the driver function for the 

device-independent/device-dependent interface. The name of the function 
corresponding to tlte desired view surface type should be put into vwsurf.dd prior 
to calling initialize_view_surf ace () (see the programming examples 
in Chapters 1 and 8). 

The current release of SunCore has eight view surface types: 
bwldd 

The Sun-1 monochrome bitmap display used as a raw device. 
bw2dd 

The Sun-2 or Sun-3 monochrome bitmap display used as a raw device. 
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cgldd 

The Sun-1 color graphics display used as a raw device. 
cgldd 

The Sun-2 or Sun-3 color graphics display used as a raw device. 
cg4dd 

The Sun-3/110 color display used as a raw device. 
pixwindd 

A monochrome (one bit deep) graphics window within the Suntools window 
environment. This window may appear on either a color or monochrome 
display. 

cgpixwindd 

A color graphics window within the Suntools window environment. This 
window must appear on a color display. 

gpldd 

A Sun-2/160 or Sun-3/160 graphics display with a Graphics Processor 
option. 

gplpixwindd 

A color graphics window within the Suntools window environment running 
on a Sun-2/160 or Sun-3/160 color graphics display with a Graphics Proces¬ 
sor option. 

Only view surface types cgldd, cgldd, cg4dd, cgpixwindd, gpldd, and 
gplpixwindd support hidden surface removal. In the discussion above, gray scale 
devices are considered to be color devices. 

The term ‘raw device’ above implies that the physical device specified by 
vwsutf.screenname is used completely and only for display of graphics output 
directed to one view surface. This allows somewhat more efficient display of 
out{Mit primitives. It also implies that the user has not started up a Suntools win¬ 
dow environment using the device as a desktop. 

Low-level device-dependent functions are not part of SunCore. For efficiency, 
such functions ate necessary for some applications. The Pixrect Reference 
Manual contains information on low-level functions corresponding to bwldd, 
bw2dd, cgldd, cg2dd cg4dd and gpldd, (the ‘pixrect’ level) and 
pixwindd, cgpixwindd and gplpixwindd (the ‘pixwin’ level). 


B.3. Choosing a Vievr It may be desirable to write application programs which use different view sur- 

Surface Type within face types depending on the environment. The next two subsections provide 

an Application examples of ways to do this. The next subsection illustrates using a Shell vari- 

Program able, and the subsection after that uses the get_view_surf ace () function to 

do the job in a more general way. The source for get_view_surf ace () is 
contained in /usr/src/sun/suntool/get_view_surf ace . c. 
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Using Shell Variables to 
Determine the Environment 


- o 

Examining a Shell environment variable is one way to determine which environ- 
ment a program is running in. The following example illustrates using either a 
bw2dd (raw Sun-2 or Sun-3 monochrome display) or a pixwindd (monochrome 
window) view surface depending on whether the user is currently in the Suntools 
window environment. The WINE>OW_ME environment variable is normally 
defined in the user’s environment if and only if the window system is being used. 


Figure B-1 Selecting a View Surface from an Environment Variable 

- \ 

int bw2dd(); 

struct vwsurf rawsurface = DEFAULT_VWSURF(bw2dd); 
int pixwindd() ; 

struct vwsurf windowsurface = DEFAULT_VWSURF(pixwindd); 

main() 

{ 

struct vwsurf ^surface, *get_surface (); 


surface = get_surface(); 

initialize_view_surface(surface/ FALSE); 

select_view_surface(surface); 


) 

/* returns a pointer to an appropriate view surface */ 
struct vwsurf *get_surface() 

{ 

if (getenv(”WINDOW_ME”)) 

return(Swindowsurface); 

else 

return(&rawsurface); 

} 

V.___> 



The get_view_surface The library includes the get_view_surface () function which a 

Function programmer can use to set up a view surface structure using information from 

command-line arguments and the enviroiunent. A complete listing of 
get_view_surf ace () appears at the end of this section. 
get_view_surf ace () has the following declarations for C, FORTRAN, and 
Pascal: 
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Table B-1 Declarations of get_view_surf ace in C, FORTRAN, and Pascal 


Language 

Declaration 

C 

get_view__surf ace (vsptr ^ argv) 
struct vwsurf *vsptr; 
char **argv; 

FORTRAN 

getviewsurface(vwsurf) 
integer vwsurf(VWSURFSIZE) 

Pascal 

getviewsurface(var surfacename: 
vwsurf): integer; external; 


The elements of argv are pointers to null-terminated strings which are extracted 
from the command line that started the application program. The following frag¬ 
ment of C code illustrates the use of get_view_surf ace () for C programs: 

Figure B-2 get_view_surface £jca»i/»Ze 



get_view_surf ace () returns zero (0) if it succeeds and non-zero otherwise. 
The vwsurf structure will have vwsurf.dd and possibly vwsurf.screenname set 
to appropriate values. Other elements of the stracture will be null — the pro¬ 
grammer may modify them to suit the application, but it is not necessary. 

The only command-line option that get_view_surf ace () currently recog¬ 
nizes is the display device—d.I option, where display device is the name of the 
physical display device (/dev/fb or /dev/cgoneO for example). The vwsurf 
structure will be set up to run on this device. get_view_surface () also 


Revision A, of 9 May 1988 






122 SunCore Reference Manual 


V J 

determines if the window system is running on the device, and chooses vwsutf.dd 
appropriately. 

Using get_view_surf ace () has a disadvantage in that since it refers to all 
six SunCore types of view surfaces, any program using it will get the code for all 
six device-independent/device-dependent driver functions linked in. For this rea¬ 
son, the code for get_view_surf ace () is included here. SunCore program¬ 
mers may wish to tailor a version of this code for particular machine 
configurations and applications in order to make smaller final object code. 

The code of get_view_surf ace () contains Calls on several functions from 
libsunwindow .a — the SunView library. Details of these functions can be 
found in the SunView Programmer’s Guide and SunView System Programmer’s 
Guide. 


Figure B-3 get_view_surf ace . c Moiiu/e 

—- -- 

/* 

get_view_surface — Determines from command-line arguments and 
the environment a reasonable view surface 
for a SunCore program to run on. 

*/ 

tinclude <sunwindow/window__hs . h> 

#include <sys/file.h> 

#include <sys/ioctl.h> 
tinclude <sun/fbio.h> 
tinclude <stdio.h> 
tinclude <usercore.h> 

int bwlddO; /* All device-independent/device-dependent */ 

int bw2dd(); /* routines are referenced in this function. */ 

int cglddO; /* This means the linker will pull in all of them */ 

int cg2dd(); 

int gplddO; 

int pixwinddO ; 

int cgpixwindd(); 

int gplpixwindd(); 

static struct vwsurf nullvs = NULL^VWSURF; 

static char *devchk; 
static int devhaswindows; 

int get_view_surface(vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

{ 

int devfnd, fd, chkdevhaswindows(); 
char *wptr, dev[DEVNAMESIZE], *getenv(); 

Struct screen screen; 
struct fbtype fbtype; 
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*vsptr = nullvs; 
devfnd = FALSE; 
if (argv) 

/* 

If coinmand-line arguments are passed^ process them using 
win_initscreenfromargv (see the Programmer's Reference Manual 
for the Sun Window System). The only option used by 
get_view_surface is the -d option, allowing the user to 
specify the display device on which to run. 

*/ 

{ 

win_initscreenfromargv(&screen, argv); 
if (screen.scr_fbname[0] != ^ ^) 

{ 

/* -d option was found */ 
devfnd = TRUE; 

strncpy(dev, screen.scr_fbname, DEVNAMESIZE); 

/* 

Check to see if this device has a window system 
running on it. If so devhaswindows will be TRUE 
following the call to win__enumall. win__enumall is 
a function in libsunwindow.a. It takes a function 
as its argument, and applies this function to every 
window being displayed on any screen by the window 
system. To do this it opens each window and passes 
the windowfd to the function. The enumeration 
continues until all windows have been tried or the 
function returns TRUE. 

*/ 

devchk = dev; 
devhaswindows = FALSE; 
win^enumall(chkdevhaswindows); 

} 

} 

if (!devfnd) 

/* No -d option was specified */ 
if (wptr = getenv (”WINDOW__ME”) ) 

{ 

/* 

Running in the window system. Find the device from 
which this program was started. 

*/ 

devhaswindows == TRUE; 

if ((fd = open(wptr, 0_RDWR, 0)) < 0) 

{ 

fprintf(stderr, ”get_view_surface: Can't open %s\n”, 
wptr); 
return(1); 

} 

win_screenget(fd, &screen); 
close(fd); 

strncpy(dev, screen.scr_fbname, DEVNAMESIZE); 

} 
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else 

{ 

/* 

Not running in the window system. Assume device is 
/dev/fb. 

*/ 

devhaswindows = FALSE; 
strncpy(dev, ”/dev/fb”, DEVNAMESIZE); 

} 

/* Now have device name. Find device type. */ 
if ((fd = open(deV/ 0_RDWR, 0)) < 0) 

{ 

fprintf(stderr, ”get_view_surface: Can't open %s\n”, dev); 
return(1); 

} 

if (ioctKfd, FBIOGTYPE, &fbtype) == -1) 

{ 

fprintf(stderr^ ”get_view_surface: ioctl FBIQGTYPE failed on %s\n", 
dev) ; 

close(fd); 
return(1); 

} 

close(fd); 

/* Now have device type and know if window system is running on it. */ 
if (devhaswindows) 

switch(fbtype.fb_type) 

{ 

case FBTYPE_SUN1BW: 
case FBTYPE_SUN2BW: 

vsptr->dd == pixwindd; 

- break; 

case FBTYPE_SUN1C0L0R: 
case FBTYPE_SUN2COLOR: 

vsptr->dd = cgpixwindd; 
break; 

case FBTYPE_SUN2GP: 

vsptr-'>dd = gplpixwindd; 
break; 
default: 

fprintf(stderr^ 

”get__view_surface: %s is unknown fbtype\n”, dev) ; 
return(1); 

} 

else 

switch (fbtype. fb_type) 

{ 

case FBTYPE^SUNIBW: 

vsptr“>dd = bwldd; 
break; 

case FBTYPE_SUN2BW: 

vsptr->dd = bw2dd; 
break; 

case FBTYPE_SUNlCOLOR: 

^ sun Revision A, of 9 May 1988 
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vsptr->dd = cgldd; 
break; 

case FBTYPE_SUN2C0L0R: 
vsptr->dd = cg2dd; 
break; 

case FBTYPE_SUN2GP: 

vsptr->dd = gpldd; 
break; 
default: 

fprintf(stderr^ 

”get_view_surface: %s is unknown fbtype\n”, dev); 
return(1); 

} 

/* Now SunCore device driver pointer is set up. */ 
if (!devhaswindows || devfnd) 

/* 

If no window system on device or -d option was specified^ 
tell SunCore which device. Otherwise^ let SunCore figure 
out the device itself from WINDOW_GFX so the default 
window will be used if desired. 

*/ 

strncpy(vsptr->screenname^ dev^ DEVNAMESIZE); 
return(0); 

} 

static int chkdevhaswindows(windowfd) 
int windowfd; 

{ 

struct screen windowscreen; 

win_screenget(windowfd, &windowscreen); 
if (strcmp(devchk, windowscreen.scr_fbname) == 0) 

{ 

/* 

If this window is on the display device we are checking, set 
the flag TRUE. Return TRUE to terminate the en\imeration. 

*/ 

devhaswindows = TRUE; 
return(TRUE); 

} 

return(FALSE); 

} 


B.4. Specifying a View 
Surface for 
Initialization 


It is not necessary to specify every member of the vwsurf stmcture in order to 
initialize the view surface. If only vwsurf.dd is specified, SunCore will try to 
obtain a view surface of the specified type according to a default sequence. A 
statically allocated vwsurf structure may be set up to use this default by initial¬ 
izing the stmcture via the DEFAULT_VWSURF macro defined in 
<usercore. h>. This is a compile-time initialization. The user may exercise 
finer control over view surfaces by setting other elements of the structure as 
described below. Any members which are not specified by the user should be set 
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to zero (the integer 0, the NULL pointer, or an empty string, as appropriate). 


View Surface Specification for 
Raw Devices 


The default action for obtaining a new view surface of a raw device type is to try 
to open a sequence of devices until one is found which is of the right type and is 
not already being used. The sequence always starts with Idevijb. Then the fol¬ 
lowing names are tried depending on the view surface type: 


bwldd 

bw2dd 

cgldd 

cg2dd 

cg4dd 

gpldd 


"/dev/bwoneO ”, 
”/dev/bwtwoO”, 
”/dev/cgoneO", 
”/dev/cgtwoO ”, 
”/dev/cgfour0” 
"/dev/gpone 0 a” 


”/dev/bwonel”, . 
” / de V / b wt wo 1 ”, . 
”/dev/cgonel”, . 
*’ /dev/cgtwol ”, - 
”/dev/cgfour1”^ 
”/dev/gponeOb ”, 


, ”/dev/bwone9” 
f ”/dev/bwtwo9” 

, ”/dev/cgone9” 
f ”/dev/cgtwo9” 

.., "/dev/cgfour9” 
.,f ”/dev/gpone3d” 


If none of the names in the sequence can be successfully opened and verified to 
be of the correct type and not already in use, 
initialize__view_surface 0 fails. 

If the user wishes to specify a particular physical device for a view surface, he 
may set vwsurf.screenname to be the device name of that device. The same steps 
will be taken to tiy to open the device as for each name in the default sequence. 
However, if these steps fail, no other names will be tried, and the initialization 
will fail. 


vwsurf.cmapname and vwsurfxmapsize are only used for color view surfaces. 
For cgldd, cg2dd, cg4dd and gpldd vwsurfxmapsize is set to 256. If 
vwsurfxmapname is specified, this name is used as the name of the color map; 
otherwise SunCore will provide a unique name. 


o 


No flags are currently defined for use with raw devices. 


vwsurf.ptr provides a mechanism for passing optional initialization data to Sun- 
Core. In the case of raw devices, one such option is currently available — the 
passing of information about the adjacencies of physical screens. When the user 
creates a Suntools window enviromnent on a screen, he is also responsible for 
specifying the relationship of that screen to other screens also running Suntools 
for purposes of tracking the mouse across multiple screens. The adjacentscreens 
command may be used to do this (see the SunOS Reference Manual). However, 
when a SunCore program initializes a new view surface on a raw screen, the user 
will not previously have been able to inform the system of this adjacency 
because the new screen was previously not in use. vwsurf.ptr may be used to 
pass adjacency information for the new screen. 


If vwsurf.ptr is not NULL, it should point to an array of character pointers. Only 
the first pointer in this array will be used. It should point to a string which is the 
pathname of a file containing information about the adjacencies of physical 
display devices. When the user sets up his display devices on his desk he may 
create a file describing the layout of these devices. For example, the following 
lines describe a system with two screens, the console frame buffer on the left 
(which might be a monochrome bitmap display) and a Sun color graphics display 
on the right: 


o 
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/dev/fb 

R: /dev/cgoneO 
/dev/cgoneO 
L: /dev/fb 


By convention, Idevifb is the console frame buffer and IdevIcgoneO is the first 
Sun color graphics display on a system. For each display device in the system, 
there should be one line giving its name, followed by several lines giving the 
directions and names of all adjacent screens. Thus all four lines above are neces¬ 
sary, not just the first two. Directions may be indicated as R, L, T, and B for 
right, left, top, and bottom, or as N, S, E, and W for north, south, east, and west. 


View Surface Specification for 
Window Devices 





The default action for obtaining a new view surface of type pixwindd, 
cgpixwindd or gplpixwindd is to first test whether the window referred to by the 
Shell environment variable WINDOW_GFX is already in use as a view surface. If 
not, a blanket window is inserted over the WINDOW GFX window and this 
blanket window becomes the view surface. If WINDOWGFX has already been 
used in this manner, the program /usr/lib/view surface is invoked to 
create a new window on the same physical display device as WINDOW GFX. 

This new window becomes the view surface. Thus, if a SunCore program is run 
from the tty subwindow of a Graphics Tool, the first default view surface will 
occupy the display space covered by the grajrfiics subwindow of the tool. Subse¬ 
quent default view surfaces will appear as graphics windows, each within a 
separate View Surface Tool on the same screen as the Graphics Tool. 

This default action may be circumvented in two ways. If vwsurf.flags has the 
VWSURF NEWFLG set, no attempt is made to take over WINDOW GFX. A new 
window within a View Surface Tool is opened on the same screen as 
WlNDOW GP^. If vwsurf.screenruime is non-empty, a new window within a 
View Surface Tool is opened on the screen specified by vwsurf.screenruime, pro¬ 
vided this device exists and has a Suntools window environment mnning on it. 

For view surfaces of type cgpixwindd or gplpixwiridd, vwsurf.cmapsize 
and vwsurf.cmapname provide a means of specifying and sharing color maps. 

The color map facilities of SunView are used to control color maps for 
cgpixwindd or gplpixwindd view surfaces (see the SunView 
Programmer’s Guide). The user may specify a color map size of 0, in which 
case a color map of length 2 will be used. Otherwise, vwsurf.cmapsize should be 
a power of 2 between 2 and 256. The user may specify a null color map name, in 
which case SunCore will provide a unique name. Otherwise, SunCore will check 
vwsurf.cmapname against the names of the color maps for all windows currently 
displayed on the physical device on which the new view surface is to appear. If a 
matching name is found, that color map will be used (even if its size differs from 
vwsurf.cmapsize) and this map is shared among all windows on the device which 
reference that name. If the user specified a null name or the specified name does 
not match any current window’s color map name, a new color map is allocated 
with the given size. The indices for each cgpixwindd or gplpixwindd view 
surface’s color map run from 0 to vwsurf.cmapsize—I. 

Currently, one optional string of initialization data may be passed to 
initialize_view_surf ace (). If vwsurf.ptr is non-NULL, it should 
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point to an array of character pointers, only the first of which will be used. The 
pointer should point to a string containing position and size information for a 
Core Tool which may be started up to provide a window for the new view sur¬ 
face. (If the WINDOW_GFX window is taken over by this new view surface and 
thus no View Surface Tool is started, the string will be ignored.) The string 
should consist of nine integers, separated by commas: 

"nl,nt,nw,nh,il,it,iw,ih,I” 

nl, and nt give the initial position of the top left comer of the View Surface Tool 
in its normal form, nw and nh give the initial width and height The numbers are 
given in screen coordinates, where (0,0) is the upper left comer, il, it, iw, and ih 
give the same initial information for the iconic form of the tool. I is a boolean 
flag which should be non-zero if the tool is to be started in its iconic form. 


B.5. Input Considerations 


SunCore uses window system functions to obtain user input fiom the keyboard 
and mouse, no matter what mix of raw device view surfaces and window device 
view surfaces the user has initialized. For purposes of input, a raw device view 
surface behaves just like a window device view surface; it exists as a window 
within the window system’s data stractures, and the user may direct input to the 
window simply by positioning the mouse over it. The facts that window system 
input is directed to different windows depending on the location of the mouse 
and that the mouse position in the window system is reported in the coordinates 
of the window underlying the mouse have implications for the SunCore input 
functions. \ J 

For SunCore programs which are invoked from a window within the Suntools 
window envirorunent, whenever the KEYBOARD device is initialized, 
await_keYboard () will return characters typed when the mouse is located 
over any initialized view surface (belonging to a single user process) or over the 
tty subwindow from which the program was started. For programs mn from out¬ 
side a window environment, await keyboard will return all characters typed on 
the keyboard, provided the KEYBOARD device is initialized. 


The ACM Core specification defines input and output to be completely orthogo¬ 
nal functions. Thus, it is possible to initialize a locator device and read from it 
without ever initializing a view surface. SunCore uses the mouse as the LOCA¬ 
TOR, STROKE, PICK, VALUATOR, and BUTTON devices. The only way Sun¬ 
Core can obtain mouse position and button click information to emulate these 
logical devices is to take input from a window. SunCore will return valid data in 
response to input requests for the LOCATOR, STROKE, PICK, and VALUATOR 
devices only when the user has associated these devices with an initialized view 
surface via the set_echo_surf ace () function. Because all SunCore view 
surfaces are instantiations of generic view surface types, there is no default echo 
surface for any input device. The set_echo_surf ace () function will 
accept a NULL pointer as its surface_name argument to allow the programmer to 
end die association of an input device with a view surface. Any input device 
may be echoed on any view surface independently of any other input device. 

The input functions await_any_button_get_locator_2 (), 
await_stroke_2 (), await_pick (), and 
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await_any_button_get_valuator () will only use mouse input which 
the user directs to the window which is the echo surface for the indicated LOCA¬ 
TOR, STROKE, PICK, or VALUATOR device. This includes both position and 
button click input, so that (he functions which are terminated by button clicks 
will terminate oidy when a button click occurs within the proper window (or a 
timeout occurs). Which buttons are listened to is still controlled by individually 
initializing or terminating each BUTTON device. 

The user may also use set_echo_sur f ace () to choose from which window 
button clicks should be reported for a BUTTON device when the 
await_button () function is called; alternatively, if the echo surface for a 
BUTTON device is NULL, await_butt on () will check for button clicks from 
any view surface associated with a LOCATOR, STROKE, PICK, or VALUATOR 
device. 

Note (hat the resolution obtained from a LOCATOR, STROKE, PICK, or VALUA¬ 
TOR device is limited by the width and/or height of its echo surface window, 
since mouse position information is provided by window system input functions 
in terms of window coordinates. 


Graphics primitives drawn on a view surface as part of a temporary segment nor¬ 
mally remain visible on the view surface until a new-frame action occurs. For 
view surfaces which are windows within the Suntools window environment, 
several user actions can cause the view surface to be redrawn. Such actions 
include stretching (he enclosing tool, exposing a previously obscured portion of 
the tool, and changing from the iconic form of the tool to Ae normal form. 

When the view surface is redrawn in this marmer, all output primitives which 
previously appeared as part of temporary segments will disappear. 

When a SuwCoreprogram is run from a shelltool (1), WINDOW GFX is 
normally set to be the tooFsTty subwindow. If this window is taken over and 
blanketed to serve as a view surface, output directed to the tty subwindow (for 
example, stdout and stderr, including SunCore error messages) will not be visible 
because the blanket window obscures the tty subwindow. When the program ter¬ 
minates or the view surface is terminated, any portion of this output which has 
not scrolled out of the subwindow will be visible. The fact that the tty subwin¬ 
dow is obscured also means that there is no way to type characters to that win¬ 
dow, so that stdin will never see any input However, if the KEYBOARD device 
is initialized, special characters, such as interrupt and suspend, typed to the 
blanket window will be recognized and will have their normal effect on the user 
process. 


B.6. Notes on Window 
Device View Surfaces 
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C. 1. Alphabetical List of C Functions 







o 








Alphabetical SunCore C Function 

Reference 


This appendix contains an alphabetical list of SunCore functions and their argu¬ 
ments definitions. SunCore programs written in C must contain the statement: 

#include <usercore.h> 

at the start of each SunCore source file. 


C.l. Alphabetical List of C The list on the following pages is a complete alphabetical list of the functions in 

Functions SunCore. 



allocate_raster(rptr) 
struct { 

int width, height, 
short *bits; 

} *rptr; 


depth; 


await_any_button(tim, butnum) 
int tim; 
int *butnum; 


await_any_Jbutton_get_locator_2 (tim, locnum, butnum, x, y) 
int tim, locnum, *butnum; 
float *x, *y; 


await_anY_button__get_valuator (tim, valnum, butnum, val) 
int tim, valnum, *butnum; 
float *val; 

await_keyboard(tim, keynum, string, length) 
int tim, keynum; 
char ^string; 
int *length; 

awaitj>ick(tim, picknum, segnam, pickid) 
int tim; 

int picknum, *segnam, *pickid; 


await_stroke_2(tim, strokenum, 
int tim, strokenum, arrsize, * 
float xarray[], yarray[]; 


arrsize, 

numxy; 


xarray, yarray. 


numxy) 
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begin_batch__of_updates () 

close__retained_seginent () 

close_teinporary__seginent () 

create_retained__seginent (segname) 
int segname; 

create_temporary_segment () 

define_color_indices(surf, 12, red, grn, blu) 

struct vwsurf *surf; 
int 11, 12; 

float "^red, *grn, *blu; 

delete_all_retained_segments() 

delete_retained_segment(segname) 
int segname; 

deselect_view_surface(surfname) 
struct vwsurf *surfname; 

end_batch_of_updates() 

file_to_raster(rasfid, raster, map) 
int rasfid; 
struct { 

int width, height, depth; 
short *bits; 

} ^raster; 
struct { 

int type, nbytes; 
char *data; 

} *map; 

free_raster(rptr) 
struct { 

int width, height, depth; 
short *bits; 

} *rptr; 

get_mouse_state(devclass, devnum, x, y, buttons) 
int devclass, devnum; 
float *x, *y; 
int ^buttons; 

get_raster(surfname, xmin, xmax, ymin, ymax, xd, yd, raster) 
struct vwsurf *surfname; 

float xmin, ymin, xmax, ymax;int xd, yd; 
struct { 

int width, height, depth; 
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short *bits; 

} ^raster; 

get_view_surface(vsptr, argv) 
struct vwsurf *vsptr; 
char **argv; 

initialize_core(outlev, inlev, dim) 
int outlev, inlev, dim; 

initialize_device(devclass, devnum) 
int devclass, devnum; 

initialize_view___surface (surfname, type) 
struct vwsurf *surfname; 
int type; 

inquire_charjust(chjust) 
int *chjust; 

inquire_charpath_2 (dx, dy) 
float *dx, *dy; 

inquire_charpath_3(dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_charprecision(chqualty) 
int *chqualty; 

inquire_charsize(chwidth, cheight) 
float *chwidth, *cheight; 

inquire_charspace(space) 
float *space; 

inquire_charup_2(dx, dy) 
float *dx, *dy; 

inquire_charup_3(dx, dy, dz) 
float *dx, *dy, *dz; 

inquire_color__indices (surf, il, i2, red, grn, blu) 
struct vwsurf *surf; 
int il, i2; 

float *red, *grn, *blu; 

inquire_current j>osition__2 (x, y) 
float *x, *y; 

inquire_current_position_3(x, y, z) 
float *x, *y, *z; 

inquire^detectability(detectability) 
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int *detectability; 

inquire_echo (devclass/ devnuin^ echotype) 
int devclass, devnum^ *echotype; 

inquire_echoj>osition (devclass/- devnum, y) 
int devclass, devnum; 
float *y; 

inquire_echo_surface(devclass, devnum, surfname) 
int devclass, devnum; 
struct vwsurf *surfname; 

inquire_f ill_index (color) 
int *color; 

inquire_font (font) 
int *font; 

inquire_highlighting(highlighting) 
int ^highlighting; 

inquire_image_transformation_2(sx, sy, a, tx, ty) 
float *sx, *sy, *a, *tx, *ty; 

inquire_image_transformation_3 (sx, sy, sz, ax, ay, az, tx, ty, tz) 
float *sx, *sy, *sz, *ax, *ay, *az, *tx, *ty, *tz; 

inquire__image_transformation_type (segtype) 
int *segtype; 

inquire_image_translate_2 (tx, ty) 
float *tx, *ty; 

inquire_image_translate_3 (tx, ty, tz) 
float *tx, *ty, *tz; 

inquire_inverse_composite_matrix(arrayptr) 
float *arrayptr; 

inquire_keyboard(keynum, bufsize, istr, pos) 
int keynum, *bufsize, *pos; 
char *istr; 

inquire_line__index (color) 
int *color; 

inquire_linestyle(linestyl) 
int *linestyl; 

inquire_linewidth(linwidth) 
float *linwidth; 
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inqiiire_locator_2 (locnum, x, y) 
int locnum; 
float *y; 


inquiretinarker_syinbol (mark) 
int *mark; 


inquire_ndc_space_2 (width, height) 
float *width, *height; 

inquire_ndc_space_3(width, height, depth) 
float *width, ^height, *depth; 

inquire__open_retained__segment (segname) 
int *segname; 

inquire_open_temporary_segment (open) 
int *open; 

inquireopen(pen) 
int *pen; 


inquire_pick_id (pickid) 
int *pickid; 


inquire_polygon__edge_style (polyedgstyl) 
int *polyedgstyl; 


inquire_polygon_interiorestyle(polyintstyl) 
int *polyintstyl; 

inquire_primitive_attributes (defprim) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polyintstyl, polyedgstyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 

int chjust, chqualty; 

int marker, pickid, rasterop; 

} *defprim; 

inquire^pro jection (pro jection__type, dx__proj, dy_proj, dz^proj) 
int *projection_type; 





inquire_rasterop(rasterop) 
int *rasterop; 

inquire_retained_segment_names(listcnt, seglist, segcnt) 
int seglist[], listcnt, *segcnt; 
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inquire_retained_seginent_surfaces(segname^ arraycnt^ surfaray^ surfnum) 
int segname^ arraycnt; 
struct vwsurf surfaray[]; 
int ^surfnum; 

inquire_segment_detectability(segname, detectbl) 
int segname; 
int *detectbl; 

inquire_seginent_highlighting(segname, highlght) 
int segname; 
int *highlght; 

inquire_segment_image_transformation_2 (segname, sx, sy, a, tx, ty) 
int segname; 

float *sx, *sy, *a, *tx, *ty; 

inquire_segment_image_transformation_3(segname, sx, sy, sz, rx, ry, rz, tx, ty, tz) 
int segname; 

float *sx, *sy, *sz, *rx, *ry, *rz, *tx, *ty, *tz; 

inquire_segment_image_translate_2 (segname, tx, ty) 
int segname; 
float *tx, *ty; 

inquire_segment_image__translate__3 (segname, tx, ty, tz) 

int segname; 

float *tx, *ty, *tz; 

inquire_segment_visibility(segname, visbilty) 
int segname; 
int *visbilty; 

inquire__stroke (strokenum, bufsize, dist, time) 
int strokenum, *bufsize, *time; 
float *dist; 

inquire_text_extent_2(s, dx, dy) 

char *s; 

float *dx, *dy; 

inquire_text_extent_3(s, dx, dy, dz) 
char *s; 

float *dx, *dy, *dz; 

inquire_text_index(color) 
int *color; 

inquire_valuator(valnum, init, low, high) 
int valnum; 

float *init, *low, *high; 

inquire_view_depth(front_distance, back_distance) 
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float *front__distance/ *back_distance; 

inquire_view_plane_distance(view_distance) 
float *view__distance; 

inquire_view_j>lane__normal (dx__nonn/ dy__norm/ dz_norm) 
float *dx_norm/ *dy_norm/ *dz_norm; 

inquire_view_reference_j)oint(x_ref/ y_ref/ z_ref) 
float *x__ref/ *y_ref/ *z_ref; 

inquire_view_up_2 (dx_up/ dy__up) 
float *dx_up/ *dy_up; 

inquire__view_up_3 (dx_up/ dy_up/ dz_up) 
float *dx_up/ *dy_up/ *dz__up; 

inquire_viewing_control_parameters(windowclip/ frontclip/ backclip/ type) 
int *windowclip/ *frontclip/ *backclip/ *type; 

inquire_viewing_parameters(viewparm) 
struct { 

float vwrefpt[3]; 
float vwplnorm[3] ; 
float viewdis; 
float frontdis; 
float backdis; 
int projtype; 
float projdir[3]; 
float window[4]; 
float vwupdir[3]; 
float viewport[6] ; 

) *viewparin; 

inquire_viewport_2 (xmin/ xmax/ ymin/ ymax) 
float *xmin/ *xmax/ *ymin/ *yinax; 

inquire_viewport_3 (xmin/ xmaX/ ymin/ ymaX/ zmin/ zmax) 
float *xmin/ *xmax/ *ymin/ *ymax/ *zmin/ *zmax; 

inquire_visibility(visibility) 
int ^visibility; 

inquire_window (lomin/ umaX/ vmin/ vmax) 
float *umin/ *umax/ *vmin/ *vmax; 

inquire_world_coordinate_matrix_2(arr) 
float *arr; 

inquire_world_coordinate_matrix_3(arrayptr) 
float *arrayptr; 

line_abs_2 (X/ y) 
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float X, y; 

line_abs_3 (x, y, z) 
float X, y, z; 

line_rel__2 (dx, dy) 
float dx, dy; 

line_rel_3(dx, dy, dz) 
float dx, dy, dz; 

map_ndc_to_world_2(ndcx, ndcy, wldx, wldy) 
float ndcx, ndcy, *wldx, *wldy; 

map_ndc_to_world_3(ndcx, ndcy, ndcz, wldx, wldy, wldz) 
float ndcx, ndcy, ndcz, *wldx,. *wldy, *wldz; 

map_world_to_ndc_2(wldx, wldy, ndcx, ndcy) 
float wldx, wldy, *ndcx, *ndcy; 

map_world_to_ndc_3 (wldx, wldy, wldz, ndcx, ndcy, ndcz) 
float wldx, wldy, wldz, *ndcx, *ndcy, *ndcz; 

inarker_abs_2 (mx, my) 
float mx, my; 

marksr_abs_3 (mx, my, mz) 
float mx, my, mz; 

marksr_rel_2 (dx, dy) 
float dx, dy; 

marksr_rsl_3(dx, dy, dz) 
float dx, dy, dz; 

move_abs_2 (x, y) 
float X, y; 

movs_abs_3 (x, y, z) 
float X, y, z; 

movs_rsl_2(dx, dy) 
float dx, dy; 

movs_rel_3(dx, dy, dz) 
float dx, dy, dz; 

nsw_frams() 

polygon_abs_2(xlist, ylist, n) 
float *xlist, *ylist; 
short n; 
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polygon_abs_3(xlistr ylist, zlist, n) 
float *xlist, *ylist, *zlist; 
int n; 

polygon_rel___2 (xlist, ylist, n) 
float *xlist, *ylist; 
short n; 

polygon_rel_3(xlist/ ylist, zlist/ n) 
float *xlist, *ylist, *zlist; 
int n; 

polyline_abs_2(xcoord, ycoord^ n) 
float xcoord[], ycoord[]; 
int n; 

polyline_abs_3(xcoord, ycoord, zcoord, n) 
float xcoord[]/ ycoord[]/ zcoord[]; 
int n; 

polyline_rel__2 (xcoord^ ycoord, n) 
float xcoord[], ycoord[]; 
int n; 


polyline_rel_3(xcoord, ycoord, zcoord, 
float xcoord[], ycoord[], zcoord[]; 
int n; 


n) 


polymarker_abs_2(xcoord, ycoord, n) 
float xcoord[], ycoord[]; 
short n; 


polymarker__abs_3 (xcoord, ycoord, zcoord, n) 
float xcoord[], ycoord[], zcoord[]; 
int n ; 


polyinarker_rel_2 (xcoord, ycoord, n) 
float xcoord[], ycoord[]; 
int n; 


polymarker_rel__3 (xcoord, ycoord, zcoord, n) 
float xcoord[], ycoord[], zcoord[]; 
int n; 


print_error(string, error) 
char ^string; 
int error; 


put_raster(srast) 
struct { 

int width, height, depth; 
short *bits; 

} *srast; 
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raster_to_file(raster, map, rasfid, n) 
struct { 

int width, height, depth; 
short *bits; 

} *raster; 
struct { 

int type, nbytes; 
char *data; 

} *map; 

int rasfid, n; 

rename_retained_segment (segname, newname) 
int segname, newname; 

report_most_recent_error(error) 
int *error; 

restore_segment(segname, filename) 
int segname; 
char *filename; 

save_segment(segnum, filename) 
int segnum; 
char *filename; 

select_view_surface(surfname) 
struct vwsurf *surfname; 

set_back_j>lane_c lipping (onof f) 
int onoff; 

set_charjust(chjust) 
int chjust; 

set_charpath___2 (dx, dy) 
float dx, dy; 

set_charpath_3(dx, dy, dz) 
float dx, dy, dz; 

set_charprecision(chqualty) 
int chqualty; 

set_charsize(chwidth, cheight) 
float chwidth, cheight; 

set_charspace(space) 
float space; 

set_charup_2(dx, dy) 
float dx, dy; 

set_charup_3 (dx, dy, dz) 
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float dx, dy, dz; 

set__coordinate_system_type (type) 
int type; 

set_detectability(detectability) 
int detectability; 

set_drag(drag) 
int drag; 

set_echo(devclass, devnum^ echotype) 
int devclass, devnum/ echotype; 

set_echo_group(classf devnum, n, echotype) 
int clasSf devnum[], n, echotype; 

set_echo_position (devclass^ devntim, y) 
int devclass, devnum; 
float X, y; 

set_echo_surface(devclass, devnum, surfname) 
int devclass, devnum; 
struct vwsurf *surfname; 

set_fill__index (color) 
int color; 

set_font(font) 
int font; 

set_f ront j>lane_clipping(onoff) 
int onoff; 

set_highlighting(highlighting) 
int highlighting; 

set_image_transformation_2(sx, sy, a, tx, ty) 
float sx, sy, a, tx, ty; 

set_image_transformation_3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
float sx, sy, sz, ax, ay, az, tx, ty, tz; 

set_image_t rans formation_type(type) 
int type; 

set_image_translate_2(tx, ty) 
float tx, ty; 

set_image_translate_3 (tx, ty, tz) 
float tx, ty, tz; 

set_keyboard(keynum, bufsize, istr, pos) 
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int keynum^ bufsize^ pos; 
char *istr; 

set_light_direction(dx, dy, dz) 
float dx^ dy, dz; 

set_line_index(color) 
int color; 

set_linestyle(linestyl) 
int linestyl; 

set__linewidth (linwidth) 
float linwidth; 

set_locator_2(locnum, x, y) 
int locnum; 
float X, y; 

set_jmarker_symbol (mark) 
int mark; 

set_ndc_space_2(width, height) 
float width, height; 

set_ndc_space_3(width, height, depth) 
float width, height, depth; 

set__output_c lipping (onof f) 
int onoff; 

set j>en (pen) 
int pen; 

set_pick_id(pickid) 
int pickid; 

set_polygon_edge_style(polyedgstyl) 
int polyedgstyl; 

set_j3olygon_interior_style (polyintstyl) 
int polyintstyl; 

set_primitive___attributes (defprim) 
struct { 

int lineindx, fillindx, textindx; 
int linestyl, polyintstyl, polyedgstyl; 
float linwidth; 
int pen, font; 

float charwidth, charheight; 

float charupx, charupy, charupz, charupw; 

float charpathx, charpathy, charpathz, charpathw; 

float charspacex, charspacey, charspacez, charspacew; 
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int chjust, chqualty; 
int marker, pickid, rasterop; 
*defprim; 


set_projection(projtype, dx, dy, dz) 
int projtype; 
float dx, dy, dz; 


set_rasterop(flag) 
int flag; 

set_segment_detectability(segname, detectbl) 
int segname; 
int detectbl; 

set_segment__highlighting (segname, highlght) 
int segname; 
int highlght; 


set_segment_image_transformation_2 (segname, sx, sy, a, tx, ty) 
int segname; 

float sx, sy, a, tx, ty; 



set_segment_image_translate_2 (segname, tx, ty) 
int segname; 
float tx, ty; 


set_segment_image_translate_3 (segname, dx, dy, dz) 
int segname; 
float dx, dy, dz; 


set_segment_image_transformation_3 (segname, . sx, sy, sz, rx, ry, rz, tx, ty, tz) 
int segname; 

float sx, sy, sz, rx, ry, rz, tx, ty, tz; 

set__segment_visibility(segname, visbilty) 
int segname; 
int visbilty; 


set_shadingj)arameters(amb, dif, spec, flood, bump, hue, style) 
float amb, dif, spec, flood, bump; 
int hue, style; 


set__stroke (strokenum, bufsize, dist, time) 
int strokenum, bufsize, time; 
float dist; 

set_text_index(color) 
int color; 

set__valuator (valnum, init, low, high) 
int valnum; 

float init, low, high; 
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set_vertex_indices(indxlist/ n) 
int *indxlist/ n; 

set__vertex_norinals (dxlist/ dylistf dzlist, n) 
float *dxlist, *dylist, *dzlist; 
int n; 

set_view_depth(near, far) 
float near, far; 

set_view_plane_distance(dist) 
float dist; 

set_view_jDlane__normal (dx, dy, dz) 
float dx, dy, dz; 

set_view_reference__point (x, y, z) 
float X, y, z; 

set_view__up_2 (dx, dy) 
float dx, dy; 

set_view_up_3(dx, dy, dz) 
float dx, dy, dz; 

set_viewing_j)araineters (viewparm) 
struct { 

float vwrefpt[3]; 
float vwplnorm[3]; 
float viewdis; 
float frontdis; 
float backdis; 
int projtype; 
float projdir[3]; 
float window[4]; 
float vwupdir[3]; 
float viewport[6] ; 

} *viewparm; 

set_viewport_2 (xmin, xmax, ymin, ymax) 
float xmin, xmax, ymin, ymax; 

set_viewport_3 (xmin, xmax, ymin, ymax, zmin, zmax) 
float xmin, xmax, ymin, ymax, zmin, zmax; 

set_visibility(visibility) 
int visibility; 

set_window (umin, umax, vmin, vmax) 
float umin, umax, vmin, vmax; 

set_window_clipping(onoff) 
int onoff; 
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set_world_coordinate_inatrix__2 (array) 
float *array; 

set_world_coordinate__matrix_3 (array) 
float *array; 

set_zbuffer_cut(surf, xarr, zarr, n) 
struct vwsurf *surf; 
float xarr[], zarr[]; 
int n ; 

size_raster(surfname, xmin, xmax, ymin, ymax, raster) 
struct vwsurf *surfname; 
float xmin, ymin, xmax, ymax; 
struct { 

int width, height, depth; 
short *bits; 

) *raster,; 

terminate_core() 

terminate_device (devclass, devntim) 
int devclass, devnum; 

terminate_view_surface(surfname) 
struct vwsurf *surfname; 

text(string) 
char ^string; 
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Using SunCore with Fortran-77 

Programs 

All functions provided in SunCore may be called from FORTRAN-77 programs 
by linking them with the /usr/lib/libcore77 . a library. This is done by 
using the f77 compiler with a command line such as: 

^^ 

% f77 -fswitch -o grab grab.f -lcore77 -Icore -Isunwindow -Ipixrect -Im 

_ I 

where grab. f is the FORTRAN source program. The -f switch option will 
cause the compiler to take advantage of floating point hardware if it is available. 
Otherwise, the compiler will emulate this floating point support with software. 
(For more information on floating point options, see Appendix F). Note that 
/usr/lib/libcore. a must be linked with the program (the -Icore 
option), and /usr/lib/libcore77 . a must come before it (the —lcore77 
option). 

Defined constants may be referenced in source programs by including 
/usr/include/f 77/usercore77 .h In a FORTRAN program, this must be 
done via a source statement like: 

include "/usr/include/f77/usercore77.h" 

This include statement must be in each FORTRAN program unit which uses the 
defined constants, not just once in each source program file. The default primi¬ 
tive attribute structure PRIMATTS which is provided in <usercore. h> and is 
described in section 6.1.23 of this manual is not provided in usercore77 . h 
because of FORTRAN’S restrictions on (he ordering of specification statements 
and data statements. 

In the Sun release of FORTRAN-77, names are restricted to sixteen characters in 
length and may not contain the underline character. For this reason, FORTRAN 
programs must use abbreviated names to call the corresponding SunCore func¬ 
tions. The correspondence between the full SunCore names and the FORTRAN 
names appears later in this appendix. In addition, FORTRAN-77 declarations for 
all SunCore functions appear at the end of this appendix. 
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D.l. Programming Tips 


f^] 

o The abbreviated names of the SunCore functions are less readable than the full 
length names because the underline character cannot be used in the FORTRAN 
names. However, since FORTRAN doesn’t distinguish between upper-case and 
lower-case letters in names, upper-case characters can be used to improve rea¬ 
dability. There is an example of this later in this appendix. 

□ Character strings passed from FORTRAN programs to SunCore caimot be 
longer than 256 characters. 

□ FORTRAN passes all arguments by reference. Although some SunCore func¬ 
tions receive arguments by value, the FORTRAN programmer need not worry 
about this. The interface routines in /usr/lib/libcore77 . a handle this 
situation correctly. When in doubt, look at the FORTRAN declarations for 
SunCore subroutines at the end of this appendix. 

□ SunCore uses pointers in some places. For instance, view surface structures 
contain pointers to device driver functions. Also, the raster data type includes 
a pointer to an array of short’s containing the raster data. There are no pointer 
types in FORTRAN, but there are ways to handle all uses of pointers required 
to use SunCore. For view surface names, the following fragments of C code 
and FORTRAN code do the same thing: 


Table D-1 Comparison of C and FORTRAN Statements 


C Code 

FORTRAN Code 

struct vwsurf vsurf = NULL_VWSURF; 

integer vsurf(VWSURFSIZE) 

int bwldd 0 ; 

integer bwldd 


external bwldd 

vsurf.dd = bwldd; 

data vsurf /VWSURFSIZE*0/ 


vsurf(DDINDEX) = loc(bwldd) 

initial!ze_view_surface(Svsurf, FALSE); 

call InitializeVwsurf(vsurf, FALSE) 




The constants VWSURFSIZE and DDINDEX are defined in 
usercore77 , h. The constant VWSURFNEWFLG is also defir^d in 
usercore77.h. 


bwldd 

The Sun-1 monochrome bitmap display used as a raw device. 
bwldd 

The Sun-2 or Sun-3 monochrome bitmap display used as a taw device. 
cgldd 

The Sun-1 color graphics display used as a raw device. 
cgldd 

The Sun-2 or Sun-3 color graphics display used as a taw device. 
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Cg4dd 

The Suii-3/110 color display used as a raw device. 
pixwindd 

A monochrome (one bit deep) graphics window within the Suntools 
window environment. This window may appear on either a color or 
monochrome display. 

cgpixwindd 

A color graphics window within the Suntools window environment. 

This window must appear on a color display. 

gpldd 

A Sun-2/160 or Sun-3/160 graphics display with a Graphics Processor 
option. 

gplpixwindd 

A color graphics window within the Suntools window environment ran- 
ning on a Sun-2/160 or Sun-3/160 color graphics display with a Graph¬ 
ics Processor option. 

Only view surface types cgldd, cg2dd, cg4dd, cgpixwindd, gpldd, and 
gplpixwindd support hidden surface removal. In the discussion above, gray 
scale devices are considered to be color devices. 

As shown above, all required pointer manipulation can be done with the 
FORTRAN loc library subroutines, which returns the address of its argu¬ 
ment as an integer. 

SunCore function arguments which are pointers to structures can be declared 
as arrays in FORTRAN. For example, the C and FORTRAN declarations of 
the SunCore raster structure are shown below: 


C Code 

FORTRAN Code 

struct { 

integer raster(4) 

int width, height, depth; 


short *bits; 


} raster; 



Then the following fragments of C and FORTRAN code are equivalent: 


C Code 

FORTRAN Code 

short data[16]; 

integer*2 

data(16) 

raster.width = 16; 

raster(1) 

= 16 

raster.height = 16; 

raster(2) 

- 16 

raster.depth = 1; 

raster(3) 

= 1 

raster.bits = data; 

raster(4) 

= loc(data) 


□ Some SunCore structures contain both andint’s float’s. For instance, the 
argument to inquire_viewing_parameters () contains bothint’s and 
float’s. This can be handled in FORTRAN by declaring a REAL array and 
an INTEGER array which are made to share storage by an EQUIVALENCE 
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Statement. Then following the call to the inquiry function, the REAL com¬ 
ponents can be accessed by using the REAL array and the INTEGER com¬ 
ponents accessed via the INTEGER array. 

□ Since FORTRAN does not distinguish between upper-case and lower-case 
letters in identifiers, any FORTRAN program unit which includes the 
user core77 . h header file cannot use identifiers with the same spelling as 
any constant defined in that header file (regardless of case). 

□ The f iletoraster and rastertof ile functions in C take an argument 
that is a UNIXt file descriptor. The corresponding argument to the FORTRAN 
functions is a logical unit number (LUN). This unit should be explicitly 
opened by using the FORTRAN open statement. I/O to the opened file should 
be done only via the f iletoraster and rastertof ile functions. 

D.2* Example Program This example is the FORTRAN equivalent of the very simple program for draw¬ 

ing a martini glass. 


include ”/usr/include/f77/usercore77.h" 

integer vsurf(VWSURFSIZE) 
integer pixwindd 
external pixwindd 

integer InitializeCore, InitializeVwsurf^ SelectVwsurf 
real glassdx(9), glassdy(9) 

data glassdx /-lO.0,9.0,0.0,-14.0,30.0,-14.0,0.0,9.0,-10.0/ 
data glassdy /O.0^1.0,19.0^15.0,0.0,-15.0,-19.0,-1.0, 0.0/ 
data vsurf /VWSURFSIZE*0/ 

vsurf (DDINDEX) == loc (pixwindd) 

if (InitializeCore(BASIC, NOINPUT, TWOD) .ne. 0) call exit(l) 

if (InitializeVwsurf(vsurf, FALSE) .ne. 0) call exit(2) 

if (SelectVwsurf(vsurf) .ne. 0) call exit(3) 

call SetViewport2(0.125, 0.875, 0.125, 0.75) 

call SetWindow(-50.0, 50.0, -10.0, 80.0) 

call CreateTempSeg() 

call MoveAbs2(0.0, 0.0) 

call PolylineRel2(glassdx, glassdy, 9) 

call MoveRel2(-12.0, 33.0) 

call LineRel2(24.0, 0.0) 

call CloseTempSeg() 

call sleep(10) 

call DeselectVwsurf(vsurf) 

call TerminateCore() 

end 

V---; 


Figure D-1 FORTRAN Example Program 


t UNIX is a registered trademark of AT&T. 
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D.3. Correspondence 

Between C Names and 
FORTRAN Names 


Table D-2 Correspondence Between C Names and FORTRAN Names 


C Name 

FORTRAN Name 

allocate raster 

allocateraster 

await any button 

awaitanybutton 

await any button get locator 2 

awtbuttongetloc2 

await any button get valuator 

awtbuttongetval 

await keyboard 

awaitkeyboard 

await_pick 

awaitpick 

await stroke 2 

awaitstroke2 

b e g i n___b at ch_o f __up dates 

beginbat chupdat e 

close retained_segment 

closeretainseg 

close temporary segment 

closetempseg 

create retained_segment 

createretainseg 

create temperary_segment 

createtempseg 

define color indices 

defcolorindices 

delete all retained_segments 

delallretainsegs 

delete retained segment 

delretainsegment 

deselect view surface 

deselectvwsurf 

end batch of updates 

endbatchupdate 

file to raster 

filetoraster 

free raster 

freeraster 

get mouse state 

getmousestate 

get raster 

getraster 

initial!ze_core 

initializecore 

initialize_device 

initializedevice 

initialize_view_surface 

initializevwsurf 

inquire_char just 

inqcharjust 

inquire charpath___2 

inqcharpath2 

inquire_charpath_3 

inqcharpath3 

inquire_charprecision 

inqcharprecision 

inquire charsize 

inqcharsize 

inquire charspace 

inqcharspace 

inquire__charup_2 

inqcharup2 

inquire_charup_3 

inqcharup3 

inquire_color__indices 

inqcolorindices 

inquire_current__position__2 

inqcurrpos2 

inquire__current__position___3 

inqcurrpos3 

inquire_detectability 

inqdetectability 

inquire_echo 

inqecho 

inquire_echopposition 

inqechoposition 

inquire echo_surface 

inqechosurface 

inquire fill index 

inqfillindex 

inquire_font 

inqfont 

inquire highlighting 

inqhighlighting 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 

C Name 

FORTRAN Name 

inquire_image__transformation_2 

inqimgtransform2 


inquire_image_transformation 3 

inqimgtransform3 


inquire___image_trans format ion_type 

inqimgxformtype 


inquire_image translate 2 

inqimgtranslate2 


inquire_image_translate_3 

inqimgtranslate3 


inquire__inverse composite matrix 

inqinveompmatrix 


inquire keyboard 

inqkeyboard 


inquire__line_index 

inqlineindex 


inquire_linestyle 

inqlinestyle 


inquire_linewidth 

inqlinewidth 


inquire_locator_2 

inqlocator2 


inquire_marker__symbol 

inqmarkersymbol 


inquire ndc space 2 

inqndcspace2 


inquire ndc space 3 

inqndcspace3 


inquire__open_retained__segment 

inqopenretainseg 


inquire_open_temporary_segment 

inqopentempseg 


inquirej)en 

inqpen 


inquire j>ick_id 

inqpickid 


inquire_polygon edge style 

inqpolyedgestyle 


inquire_polygon_interior_style 

inqpolyintrstyle 


inquire_primitive_attributes 

inqprimattrib s 


inquire_projection 

inqprojection 


inquire rasterop 

inqrasterop 


inquire_retained_segment_names 

inqretainsegname 


inquire_retained_segment surfaces 

inqretainsegsurf 


inquire_segment_detectability 

inqsegdetectable 


inquire_segment_highlighting 

inqseghighlight 


inquire_segment_image_transformation 2 

inqsegimgxform2 


inquire_segment_image_transformation 3 

inqsegimgxform3 


inquire___segment__image transformation type 

inqsegimgxfrmtyp 


inquire_segment_image__translate 2 

inqsegimgxlate2 


inquire_segment_image_translate 3 

inqsegimgxlate3 


inquirers egment_visibility 

inqsegvisibility 


inquire_stroke 

inqstroke 


inquire text extent 2 

inqtextextent2 


inquire__text_extent 3 

inqtextextent3 


inquire_text index 

inqtextindex 


inquire valuator 

inqvaluator 


inquire view depth 

inqviewdepth 


inquire_view_jplane_di stance 

inqviewplanedist 


inquire_view__j5lane_normal 

inqviewplanenorm 


inquire_view_referencej)oint 

inqviewrefpoint 


inquire view up 2 

inqviewup2 


inquire_view_up_3 

inqviewup3 


inquire_viewing_control__parameters 

inqvwgcntrlparms 


inquire_viewing_parameters 

inqviewingparams 
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Table D-2 Correspondence Between C Ncanes and FORTRAN Names — Continued 


C Name 


FORTRAN Name 



inquire viewport_2 


inqviewport2 



inquire viewport_3 


inqviewpor13 



inquire___visibility 


inqvisibility 



inquire_window 


inqwindow 



inquire world coordinate 

matrix 2 

inqworldmatrix2 



inquire world coordinate 

matrix 3 

inqworldmatrix3 



line abs 2 


lineabs2 



line abs 3 


lineabsS 



line rel 2 


linerel2 



line rel 3 


linerel3 



map ndc to world 2 


mapndctoworld2 



map ndc to world 3 


mapndctoworld3 



map world tondc_2 


map wo r 1 dt on dc 2 



map world to ndc3 


mapworldtondcS 



marker abs 2 


markerabs2 



marker abs 3 


markerabs3 



marker rel 2 


markerrel2 



marker rel 3 


markerrel3 



move abs 2 


moveabs2 



move abs 3 


moveabs3 



move rel 2 


moverel2 



move rel 3 


moverel3 



new frame 


newframe 



polygon abs 2 


polygonabs2 



polygon_abs_3 


polygonabs3 



polygon rel 2 


polygonrel2 



polygon_rel_3 


polygonrel3 



polyline_abs__2 


polylineabs2 



polyline_abs_3 


polylineabs3 



polyline rel 2 


polylinerel2 



polyline rel 3 


polylinerel3 



po 1 ymar ke r_ab s_2 


polymarkerabs2 



polymarker_abs_3 


polymarkerabs3 



polymarker rel 2 


polymarkerrel2 



polymarker rel 3 


polymarkerrel3 



print__error 


printerror 



put_raster 


putraster 



raster_to_f ile 


rastertofile 



rename retained segment 


renameretainseg 



report_most_recent___error 


reportrecenterr 



restore segment 


restoresegment 



save_segment 


savesegment 



select_view_surface 


selectvwsurf 



set_back_plane_clipping 


setbackclip 


( ' 

set_charjust 


setcharjust 



set_charpath_2 


setcharpath2 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 


C Name 

FORTRANName 

set_charpath_3 

setcharpath3 

set_charprecision 

setcharprecision 

set_charsize 

setcharsize 

s et_char spa ce 

setcharspace 

set_charup_2 

setcharup2 

set_charup 3 

setcharup3 

set coordinate system type 

setcoordsystype 

set_detectability 

setdetectability 

set_drag 

setdrag 

set_echo 

setecho 

set_echo_group 

setechogroup 

set_echo^osition 

setechoposition 

set echo surface 

setechosurface 

set fill index 

setfillindex 

set font 

setfont 

set_front_plane_clipping 

setfrontclip 

set highlighting 

sethighlighting 

set_image transformation 2 

setimgtransform2 

set_image_transformation 3 

setimgtransform3 

set_image_transformation type 

setimgxformtype 

set_image translate 2 

setimgtranslate2 

set_image translate 3 

setimgtranslate3 

set_keyboard 

setkeyboard 

set_light_direction 

setlightdirect 

set_line_index 

setlineindex 

set linestyle 

setlinestyle 

set_linewidth 

setlinewidth 

set_locator_2 

setlocator2 

s e t_mar ke r_s ymbo 1 

setmarkersymbol 

s e t _n dc_s p a c e_2 

setndcspace2 

set ndc space 3 

setndcspace3 

set_output_clipping 

setoutputclip 

set_pen 

setpen 

set_pick 

setpick 

set_pick id 

setpickid 

®^^--«Poly9on_edge_style 

setpolyedgestyle 

setj>olygon interior style 

setpolyintrstyle 

set_primitive attributes 

setprimattribs 

set_projection 

setprojection 

set_rasterop 

setrasterop 

set_segment___detectability 

setsegdetectable 

set_segment highlighting 

setseghighlight 

set_segment_image transformation 2 

setsegimgxform2 

s e t_s e gme nt_image_t r an s f or mat ion 3 

setsegimgxform3 

set_segment_image_translate 2 

setsegimgxlate2 

set_segment_image translate 3 

setsegimgxlate3 
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Table D-2 Correspondence Between C Names and FORTRAN Names — Continued 


C Name 

FORTRANName 

set segment visibility 

setsegvisibility 

set_shading__parameters 

setshadingparams 

set_stroke 

setstroke 

s e t __t e X t_i n de x 

settextindex 

set_valuator 

setvaluator 

set vertex indices 

setvertexindices 

set_vertex_normals 

setvertexnormals 

set_view_depth 

setviewdepth 

set_view_j)lane_ciistance 

setviewplanedist 

set_view_plane_normal 

setviewplanenorm 

set_view_reference_point 

setviewrefpoint 

set viewport 2 

set viewpor12 

set_viewport_3 

setviewport3 

set_view up_2 

setviewup2 

set view_up 3 

setviewup3 

set viewing parameters 

setviewingparams 

set_visibility 

setvisibility 

set window 

setwindow 

set window clipping 

setwindowc1ip 

set_world_coordinate_matrix_2 

setworldmatrix2 

set__world__coordinate_matrix 3 

setworldmatrix3 

set_zbuf f er__cut 

setzbuffercut 

size raster 

sizeraster 

terminate core 

terminatecore 

terminate_device 

terminatedevice 

terminate view surface 

terminatevwsurf 

text 

text 


D.4. FORTRAN Interfaces Note: Although all SunCore procedures are declared here as functions, each may 

to SunCore also be called as a subroutine if the user does not want to check the returned 

value. 

integer function allocateraster(raster) 
integer raster(4) 

integer function awaitanybutton(time, buttonnum) 
integer time, buttonnum 


integer function awtbuttongetloc2(time, locatornum, buttonnum, x, y) 
integer time, locatornum, buttonnum 
real x, y 

integer function awtbuttongetval(time,valuatornum,buttonnum,value) 
integer time, valuatornum, buttonnum 
real value 


integer function awaitkeyboard(time, keyboardnum, inputstring. 


length) 
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integer time, keyboardnum 
character*(*) inputstring 
integer length 

integer function awaitpick(time, picknum, segname, pickid) 
integer time, picknum, segname, pickid 

integer function awaitstroke2(time, strokenum, arraysize, xarray, yarray, n) 
integer time, strokenum, arraysize 
real xarray, yarray 
integer n 

integer function beginbatchupdate() 

integer function closeretainseg() 

integer function closetempseg() 

integer function createretainseg(segname) 
integer segname 

integer function createtempseg() 

integer function defcolorindices(surfacename, il, i2, red, green, blue) 
integer surfacename(*) 
integer il, i2 

real red(*), green(*), blue(*) 

integer function delallretainsegs() 

integer function delretainsegment(segname) 
integer segname 

integer function deselectvwsurf(surfacename) 
integer surfacename(*) 

integer function endbatchupdate() 

integer function filetoraster(rasfid, raster, map) 
integer rasfid 
integer raster(4) 
integer map(3) 

integer function freeraster(raster) 
integer raster(4) 

integer function getmousestate(devclass, devnum, x, y, buttons) 
integer devclass, devnum 
real x, y 
integer buttons 

integer function getraster(surfacename, xmin, xmax, ymin, ymax, xd, yd, raster) 
integer surfacename(*) 
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real xmin^ xmax, ymin, ymax 
integer xd, yd 
integer raster(4) 


integer function initializecore(outputlevel, inputlevel/ dimension) 
integer outputlevel, inputlevel, dimension 


integer function initializedevice(deviceclass, devicenum) 
integer deviceclass, devicenum 


integer function initializevwsurf(surfacename, type) 
integer surfacename(*) 
integer type 


integer function inqcharjust(just) 
integer just 


integer function inqcharpath2(dx, dy) 
real dx, dy 


integer function inqcharpathS(dx, dy, dz) 
real dx, dy, dz 


integer function inqcharprecision(charprecision) 
integer charprecision 


integer function inqcharsize(charwidth, charheight) 
real charwidth, charheight 


integer function inqcharspace(charspace) 
real charspace 


integer function inqcharup2(dx, dy) 
real dx, dy 

integer function inqcharupS(dx, dy, dz) 
real dx, dy, dz 


integer function inqcolorindices(surfacename, il, i2, red, green, blue) 
integer surfacename(*) 
integer il, i2 

real red(*), green(*), blue(*) 

integer function inqcurrpos2(x, y) 
real x, y 

integer function inqcurrposS(x, y, z) 
real x, y, z 



integer function inqdetectability(detectability) 
integer detectability 

integer function inqecho(deviceclass, devicenum, echotype) 
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integer deviceclass, devicenum, echotype 

integer function inqechoposition(deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 


integer function inqechosurface(deviceclass, devicenum, surfacename) 
integer deviceclass, devicenum 
integer surfacename(*) 

integer function inqfillindex(index) 
integer index 


integer function inqfont(font) 
integer font 


integer function inqhighlighting(highlighting) 
integer highlighting 

integer function inqimgtransform2(sx, sy, a, tx, ty) 
real sx, sy, a, tx, ty 


integer function inqimgtransform3(sx, sy, sz, ax, ay, az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 


integer function inqimgxformtype(type) 
integer type 

integer function inqimgtranslate2(tx, ty) 
real tx, ty 

integer function inqimgtranslateS(tx, ty, tz) 
real tx, ty, tz 


integer function inqinvcompmatrix(array) 
real array(4,4) 


integer function inqkeyboard(keyboardnum, buffersize, initstring, initcursor) 
integer keyboardnum, buffersize 
character*(*) initstring 
integer initcursor 


integer function inqlineindex(index) 
integer index 


integer function inqlinestyle(linestyle) 
integer linestyle 

integer function inqlinewidth(linewidth) 
real linewidth 


integer function inqlocator2(locatornum, x, y) 
integer locatornum 
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real x, y 

integer function inqmarkersymbol(symbol) 
integer symbol 

integer function inqndcspace2(width, height) 
real width, height 

integer function inqndcspaceS(width, height, depth) 
real width, height, depth 

integer function inqopenretainseg(segname) 
integer segname 

integer function inqopentempseg(open) 
integer open 

integer function inqpen(pen) 
integer pen 

integer function inqpickid (piclcid) 
integer pickid 

integer function inqpolyedgestyle(style) 
integer style 

integer function inqpolyintrstyle(style) 
integer style 

integer function inqprimattribs(primattr) 
integer primattr(28) 

Note: The actual argument in the calling program corresponding to primattr should be an array which can be refer¬ 
enced both as a real array and as an integer array in order to access both integer valued and real valued primitive attri¬ 
butes. This can be done using the equivalence statement. 

integer function inqprojection(projection, dxproj, dyproj, dzproj) 
integer projection real dxproj, dyproj, dzproj 

integer function inqrasterop(rop) 
integer rop 

integer function inqretainsegname(arraysize, namearray, numberofsegments) 
integer arraysize, namearray(*), numberofsegments 

integer function inqretainsegsurf(segname, arraysize, vwsurfarray, numsurf) 
integer segname, arraysize 
integer vwsurfarray(*) 
integer numsurf 

Note: arraysize should give the number of view surface structures which can be held in vwsurfarray. Each structure 
requires VWSURFSIZE elements of vwsurfarray. 

integer function inqsegdetectable(segname, detectability) 
integer segname, detectability 
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integer function inqseghighlight(segname^ highlighting) 
integer segname, highlighting 


integer function inqsegiingxforin2 (segname^ sx, sy, a, tx, ty) 

integer segname 

real sx^ sy^^ a, tx^ ty 


integer function inqsegimgxformS(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 


integer function inqsegimgxfrmtyp(segname, type) 
integer segname, type 


integer function inqsegimgxlate2(segname, tx, ty) 
integer segname 
real tx, ty 


integer function inqsegimgxlateS(segname, tx, ty, tz) 
integer segname 
real tx, ty, tz 

integer function inqsegvisibility(segname, visibility) 
integer segname, visibility 

integer function inqstroke(strokenum, bufsize, dist, time) 
integer strokenum, bufsize 
real dist 
integer time 


integer function inqtextextent2(string, dx, dy) 
character*(*) string 
real dx, dy 

integer function inqtextextent3(string, dx, dy, dz) 
character*(*) string 
real dx, dy, dz 

integer function inqtextindex(index) 
integer index 


integer function inqvaluator(valuatornum, initialvalue, low, high) 

integer valuatornum 

real initialvalue, low, high 

integer function inqviewdepth(frontdistance, backdistance) 
real frontdistance, backdistance 

integer function inqviewplanedist(viewdistance) 
real viewdistance 

integer function inqviewplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 
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integer function inqviewrefpoint(x^ z) 
real z 

integer function inqviewup2(dxup, dyup) 
real dxup, dyup 

integer function inqviewupS(dxup, dyup, dzup) 
real dxup, dyup, dzup 

integer function inqvwgcntrlparms(windowclip, frontclip, backclip, type) 
integer windowclip, frontclip, backclip, type 

integer function inqviewingparams(viewparams) 
real viewparams(26) 

Note: The actual argument in the calling program corresponding to viewparams should be an array which can be 
referenced both as a real array and as an integer array in order to access both integer valued and real valued viewing 
parameters. This can be done using the equivalence statement, 

integer function inqviewport2(xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function inqviewportS(xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 

integer function inqvisibility (visibility) 
integer visibility 


integer function inqwindow(umin, umax, vmin, vmax) 
real umin, umax, vmin, vmax 

integer function inqworldmatrix2(array) 
real array(3,3) 

integer function inqworldmatrix3(array) 
real array(4,4) 


integer function lineabs2(x, y) 
real x, y 


integer function lineabs3(x, y, z) 
real x, y, z 

integer function linerel2(dx, dy) 
real dx, dy 


integer function linerel3(dx, dy, dz) 
real dx, dy, dz 




integer function mapndctoworld2(ndcx, ndcy, 
real ndcx, ndcy, wldx, wldy 

integer function mapndctoworld3(ndcx, ndcy, 
real ndcx, ndcy, ndcz, wldx, wldy, wldz 


wldx. 


ndcz. 


wldy) 


wldx. 


wldy. 


wldz) 
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integer function inapworldtondc2(wldx, wldy^ ndcx, ndcy) 
real wldx, wldy, ndcx^ ndcy 

integer function mapworldtondcS (wldx,- wldy, wldz, ndcx, ndcy/- ndcz) 
real wldx, wldy, wldz, ndcx, ndcy, ndcz 

integer function inarkerabs2 (x, y) 
real x, y 

integer function markerabsS(X/ y, z) 
real x, y^ z 


integer function inarkerrel2 {dx, dy) 
real dx, dy 

integer function markerrelS(dx, dy, dz) 
real dx/ dy, dz 

integer function moveabs2(x, y) 
real x, y 

integer function moveabsS(x, y, z) 
real x, y^ z 

integer function moverel2(dx/ dy) 
real dx, dy 

integer function moverelS (dx,- dy, dz) 
real dx, dy, dz 


integer function newframeO 

integer function polygonabs2(xarray, yarray^ n) 
real xarray(*)/ yarray(*) 
integer n 


integer function polygonabsS(xarray^ yarray, zarray/ n) 
real xarray(*)/ yarray(*)/ zarray(*) 
integer n 

integer function polygonrel2(dxarray, dyarray^ n) 
real dxarray(*)/ dyarray(*) 
integer n 


integer function polygonrelS(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 


integer function polylineabs2(xarray, yarray, n) 
real xarray(*), yarray(*) 
integer n 


integer function polylineabs3(xarray, yarray. 


zarray, n) 
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real xarray(*), yarray(*)r zarray(*) 
integer n 

integer function polylinerel2(dxarray/ dyarray, n) 
real dxarray(*)^ dyarray(*) 
integer n 

integer function polylinerel3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 


integer function polymarkerabs2(xarray, yarray, n) 
real xarrayC^*^), yarray(*) 
integer n 

integer function polymarkerabsS(xarray, yarray, zarray, n) 
real xarray(*), yarray(*), zarray(*) 
integer n 

integer function polymarkerre12(dxarray, dyarray, n) 
real dxarray(*), dyarray(*) 
integer n 


integer function polymarkerrel3(dxarray, dyarray, dzarray, n) 
real dxarray(*), dyarray(*), dzarray(*) 
integer n 

integer function printerror(message, errornum) 
character*(*) message 
integer errornxim 

integer function putraster(raster) 
integer raster(4) 


integer function rastertofile(raster, map, rasfid, n) 
integer raster(4) 
integer map(3) 
integer rasfid, n 


integer function renameretainseg(segname, newname) 
integer segname, newname 


integer function reportrecenterr(errornum) 
integer errornum 


integer function restoresegment(segname, filename) 
integer segname 
character*(*) filename 


integer function savesegment(segname, filename) 
integer segname 
character*(*) filename 
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integer function selectvwsurf(surfacename) 
integer surfacename(*) 

integer function setbackclip(onoff) 
integer onoff 

integer function setcharjust(just) 
integer just 

integer function setcharpath2(dx, dy) 
real dx^ dy 

integer function setcharpathS(dx, dy, dz) 
real dx, dy, dz 

integer function setcharprecision(charprecision) 
integer charprecision 

integer function setcharsize(charwidth, charheight) 
real charwidth, charheight 

integer function setcharspace(charspace) 
real charspace 

integer function setcharup2(dx, dy) 
real dx, dy 

integer function setcharupS(dx, dy, dz) 
real dx, dy, dz 

integer function setcoordsystype(type) 
integer type 

integer function setdetectability(detectability) 
integer detectability 

integer function setdrag(mode) 
integer mode 

integer function setecho(deviceclass, devicenum, echotype) 
integer deviceclass, devicenum, echotype 

integer function setechogroup(deviceclass, devicenumarray, n, echotype) 
integer deviceclass, devicenumarray(*), n, echotype 

integer function setechoposition(deviceclass, devicenum, echox, echoy) 
integer deviceclass, devicenum 
real echox, echoy 

integer function setechosurface(deviceclass, devicenum, surfacename) 
integer deviceclass, devicenum 
integer surfacename(*) 
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integer function setfillindex(index) 
integer index 


integer function setfont(font) 
integer font 

integer function setfrontclip(onoff) 
integer onoff 


integer function sethighlighting(highlighting) 
integer highlighting 


integer function setiingtransform2 (sx, sy, a, tx, ty) 
real sx, sy, a^ tx, ty 


integer function setimgtransform3(sx, sy, sz, ax, ay^ az, tx, ty, tz) 
real sx, sy, sz, ax, ay, az, tx, ty, tz 


integer function setimgxformtype(type) 
integer type 


integer function setimgtranslate2(tx, ty) 
real tx, ty 

integer function setimgtranslateS(tx, ty, tz) 
real tx, ty, tz 

integer function setkeyboard(keyboardnuin, buffersize, initstring, initcursor) 
integer keyboardnuin, buffersize 
character*(*) initstring 
integer initcursor 


integer function setlightdirect(dx, dy, dz) 
real dx, dy, dz 


integer function setlineindex(index) 
integer index 


integer function setlinestyle(linestyle) 
integer linestyle 

integer function setlinewidth(linewidth) 
real linewidth 


integer function setlocator2(locatornum, x, y) 
integer locatornum 
real x, y 

integer function setmarkersymbol(symbol) 
integer symbol 

integer function setndcspace2(width, height) 
real width, height 


W 

Xr iTMCfosystems 


Revision A, of 9 May 1988 





170 SunCore Reference Manual 


integer function setndcspaceS(width, height, depth) 
real width, height, depth 


integer function setoutputclip(onoff) 
integer onoff 

integer function setpen(pen) 
integer pen 

integer function setpick(picknum, aperture) 
integer picknum 
real aperture 

integer function setpickid(pickid) 
integer pickid 

integer function setpolyedgestyle(style) 
integer style 


integer function setpolyintrstyle(style) 
integer style 

integer function setprimattribs(primattr) 
integer primattr(28) 

Note: The actual argument in the calling program corresponding to primattr should be an array which can be refer- 
enced both as a real array and as an integer array in order to access both integer valued and real valued primitive attri- 
butes. This can be done using the equivalence statement. 

integer function setprojection(projection, dxproj, dyproj, dzproj) 

integer projection 

real dxproj, dyproj, dzproj 


integer function setrasterop(rop) 
integer rop 


integer function setsegdetectable(segname, detectability) 

"integer segname, detectability 

integer function setseghighlight(segname, highlighting) 
integer segname, highlighting 

integer function setsegimgxform2(segname, sx, sy, a, tx, ty) 

integer segname 

real sx, sy, a, tx, ty 

integer function setsegimgxformS(segname, sx, sy, sz, ax, ay, az, tx, ty, tz) 
integer segname 

real sx, sy, sz, ax, ay, az, tx, ty, tz 

integer function setsegimgxlate2(segname, tx, ty) 
integer segname 
real tx, ty 
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integer function setsegimgxlateS(segname, tx^ ty, tz) 
integer segname 
real tx, ty^ tz 

integer function setsegvisibility(segname, visibility) 
integer segname, visibility 

integer function setshadingparams(ambient, diffuse, specular, flood, bump, hue, style) 
real ambient, diffuse, specular, flood, bump 
integer hue, style 

integer function setstroke(strokenum, buffersize, distance, time) 
integer strokenum, buffersize 
real distance 
integer time 

integer function settextindex(index) 
integer index 

integer function setvaluator(valuatornum, initialvalue, low, high) 

integer valuatornum 

real initialvalue, low, high 

\ 

integer function setvertexindices(colorindexlist, n) 
integer colorindexlist(*), n 

integer function setvertexnormals(xlist, ylist, zlist, n) 
real xlist(*), ylist(*), zlist(*) 
integer n 

integer function setviewdepth(frontdistance, backdistance) 
real frontdistance, backdistance 

integer function setviewplanedist(distance) 
real distance 


integer function setviewplanenorm(dxnorm, dynorm, dznorm) 
real dxnorm, dynorm, dznorm 


integer function setviewport2(xmin, xmax, ymin, ymax) 
real xmin, xmax, ymin, ymax 

integer function setviewportS(xmin, xmax, ymin, ymax, zmin, zmax) 
real xmin, xmax, ymin, ymax, zmin, zmax 


integer function setviewrefpoint(x, y, z) 
real x, y, z 

integer function setviewup2(dx, dy) 
real dx, dy 


integer function 
real dx, dy, dz 


setviewup3(dx, dy. 
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integer function setviewingparams(viewparams) 
real viewparams(26) 

Note: The actual argument in the calling program corresponding to viewparams should be an array which can be 
referenced both as a real array and as an integer array in order to access both integer valued and real valued viewing 
parameters. This can be done using the equivalence statement. 

integer function setvisibility(visibility) 
integer visibility 


integer function setwindow(umin, umax^ vmin, vmax) 
real umin^ umax, vmin, vmax 


integer function setwindowelip(onoff) 
integer onoff 


integer function setworldmatrix2(array) 
real array(3,3) 

integer function setworldmatrix3(array) 
real array(4,4) 


integer function setzbuffercut(surfacename, xlist, 
integer surfacename(*) 
real xlist(*)^ zlist(*) 
integer n 


zlist, n) I 

I 

I 



integer function sizeraster(surfacename^ xmin, xmax, ymin, ymax, raster) 

integer surfacename(^) 

real xmin^ xmax, ymin, ymax 

integer raster(4) 


integer function terminatecore() 

integer function terminatedevice(deviceclass^ devicenum) 
integer deviceclass, devicenum 


integer function terminatevwsurf(surfacename) 
integer surfacename(*) 


integer function text(string) 
character*(*) string 
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Using SunCore with Pascal Programs 


All functions provided in SunCore may be called from Pascal programs by link¬ 
ing them with the /usr/lib/libcorepas. a library by using the Pascal 
compiler with a command line of the form: 

- 

% pc -fswitch -o grab grab.p -Icorepas -Icore -Isunwindow -Ipixrect -Im 
^^_> 

where grab.p is the Pascal source program. The “f switch option will cause 
the compiler to take advantage of floating point hardware if it is available. Oth¬ 
erwise, the compiler will emulate this floating point support with software. (For 
more information on floating point options, see Appendix F). Note that 
/usr/lib/libcore. a must be linked with the program (the -Icore 
option), and /usr/lib/libcorepas . a must come before it (the —Icore¬ 
pas option). 

E.l. Programming The files typedef spas .h, usercorepas .h, devincpas .h and 

Requirements sunpas . h from the /usr/include/pascal directory must be included in 

the user’s source code to provide the necessary declarations for the Pascal inter¬ 
face to SunCore. Pascal programs which call SunCore functions must place 
these include files in the most global declaration section of the program: 

program example (input,output) 

#include ' /usr/include/pascal/usercorepas.h' 

#include '/usr/include/pascal/typedefspas.h' 

var 

{user declarations} 

finclude '/usr/include/pascal/devincpas.h' 

#include ' /usr/include/pascal/sunpas.h' 

If the Pascal program is composed of separately compiled files, these include 
statements must be in each Pascal file which uses SunCore functions and the 
corresponding defined constants. Defined constants for SunCore (see section on 
Useful Constants in the introduction to this manual) are set in the file 
/usr/include/pascal/usercorepas .h. The default primitive attri¬ 
bute structure PRIMATTS provided in user core . h and described in the section 
describing set_primitive attributes is not provided in usercorepas . h. 
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The Sun release of Pascal does not support the passing of variable length arrays 
as arguments in function or procedure calls. Therefore, fixed length arrays which 
are compatible with the Su/iCorc-Pascal interface are declared as predefined 
types in the t ypedef spas . h file (see the Declarations section of this appen¬ 
dix). The length of these arrays in 256. The length of character strings passed 
from Pascal programs to SunCore must also be 256 characters. 

The correspondence between the full SunCore names and the Pascal names 
appears in the Function Declarations section of this appendix. To provide a 
mechanism for returning the status of calls to SunCore routines, all SunCore rou¬ 
tines must be called as functions from Pascal. Finally, although most SunCore 
functions use floats (32-bit reals), Pascal uses 64-bit reals. However, the Pascal 
programmer is only required to provide reals. SunCore functions which have 
stractures as their arguments have corresponding predefined types in Pascal (see 
the Type Declarations section of this appendix). 

Routines Using View Surface View surface names in SunCore are structures containing pointers to device 
Names driver routines. The device driver names are supplied by the include file 

devincpas. h. The user may then simply use one of the names listed in Table 
E-1: 

Table E-1 Viewsurface Types 


The pasloc function (provided in the SunCore-Vs&c^ interface) transforms the 
function corresponding to the device driver into an integer which can then be 
inserted in the appropriate place in the device driver structure (see following 
example). 


Symbol 

Description 

bwldd 

Sun-1 monochrome display 

bw2dd 

Sun-2 monochrome display 

cgldd 

Sun-1 color display 

cg2dd 

Sun-2 color display 

cg4dd 

Sun-3/110 color display 

gpldd 

Graphics Processor 

pixwindd 

windows on the Sun-1 monochrome display 

cgpixwindd 

windows on a color display 

gplpixwindd 

windows with the Graphics Processor 
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Table E-2 Comparison ofC and Pascal Statements 


C Code 

Pascal Code 

struct vwsurf dsurf = NULL VWSURF; 

var 

int bwlddO; 

dsurf:vwsurf; 

• 

tstr:vwsurf st; 

• 

tstr 

dsurf.dd = bwldd; 

dsurf.dd := pasloc(bwldd); 
dsurf.screenname := tstr; 
dsurf.windowname := tstr; 
dsurf.windowfd := 0; 
dsurf.instance := 0; 
dsurf.cmapsize := 0; 
dsurf.cmapname := tstr; 
dsurf.flags := 0; 
dsurf.ptr := 0; 

initialize_view_surface(Sdsurf, FALSE); 

X := InitializeVwsurf(dsurf, FALSE); 


Assigning a literal string of two spaces (blanks) to the tstr variable will initialize 
the character array to all spaces. 


Routines Using Rasters and For uses of SunCore functions which have rasters or colormaps as arguments 

Colormaps which do not involve arithmetic direct manipulation by the programmer (for 

example, writing a raster to a file), the following restrictions on the functions do 
not apply and the programmer is only required to call the function. SunCore ras¬ 
ter and colormap structures contain pointers to variable length data (that is, 
dynamic arrays). The SunCore-Pascal interface declares these varaibles as 
integers. 

Pascal programmers wishing to alter the contents of the colormap or raster data 
within a program can write a C function which uses the pointer value returned in 
Pascal to copy the information into a fixed-length array. Arithmetic operations 
can then be perfonned on the data using conventional Pascal statements. The 
programmer can then write another G function to copy the information back into 
the array pointed to by the pointer returned by the SuMCore-Pascal interface. 
These C functions are not provided because the size of the fixed-length array will 
vary greatly among different applications. Therefore, the individual Pascal pro¬ 
grammer must decide how large an array to declare for each application. 

E.2. Example Program The use of the SunCore-Pascal interface is illustrated by showing the text of a 

program for drawing the martini glass used in previous tutorial examples. 


Figure E-1 Pascal Example Program 


- -^- 

program martiniglass (input,output); 

A 

#include '/usr/include/pascal/usercorepas.h'; 
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#include '/usr/include/pascal/typedefspas.h'; 
var 

glassdx^ glassdy: parr {type parr is an array of reals of 
length 256 declared in typedefs-h}; 

x:integer; 
dsurf:vwsurf; 
tstr:vsurfst; 

function sleep(x:integer):integer; external; 

#include '/usr/include/pascal/sunpas.h'; 

#include '/usr/include/pascal/devincpas.h'; 

procedure loaddata; 
begin 


glassdx[1] 

= -10.0; glassdy[l]. 

= 0.0; 

glassdx[2] 

= 9.0; glassdy[2] 

= 1.0; 

glassdx[3] 

= 0.0; glassdy[3] 

= 19.0; 

glassdx[4] 

= -14.0; glassdy[4] 

= 15.0; 

glassdx[5] 

= 30.0; glassdy[5] 

o 

o 

II 

glassdx[6] 

= -14.0; glassdy[6] 

= -15.0; 

glassdx[7] 

= 0.0; glassdy[7] 

= -19.0; 

glassdx[8] 

= 9.0; glassdy[8] 

= -1.0; 

glassdx[9] 

= -10.0; glassdy[9] 

II 

o 

o 


end; 

begin {main program} 

tstr := ' '; 

dsurf.screenname := tstr; 

dsurf.windowname := tstr; 

dsurf.windowfd := 0; 

dsurf.dd := pasloc(pixwindd); 

dsurf.instance := 0; 

dsurf.cmapsize := 0; 

dsurf.cmapname := tstr; 

dsurf.flags := 0; 

if (initializecore(BASIC, NOINPUT, TWOD) <> 0) then 

writeln (' error 1') 

else 

if (initializevwsurf(dsurf, FALSE) <> 0) then 
writeln (' error 2') 
else 

if (selectvwsurf(dsurf) <> 0) then 
writeln (' error 3') 
else 

X := setviewport2(0.125, 0.875, 0.125, 0.75); 
X := setwindow(-50.0, 50.0, -10.0, 80.0); 

X := createtempseg; 

X := moveabs2(0.0, 0.0); 
loaddata; 

X := polylinerel2(glassdx, glassdy,9); 

X moverel2(-12.0, 33.0); 

X := linerel2(24.0, 0.0); 

X := closetempseg; 


W 
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X := sleep(lO); 

X := deselectvwsurf(dsurf); 

X := terminatecore; 

end. 

^ _ / 


E.3. Correspondence 

Between C Names and 
Pascal Names 


Table E-3 Correspondence Between C Names and Pascal Names 


C Name 

Pascal Name 

allocate__raster 

allocateraster 

await_any_jDutton 

awaitanybutton 

await_any_button_get_locator_2 

awtbuttongetloc2 

await any button get valuator 

awtbuttongetval 

await__keyboard 

awaitkeyboard 

await_pick 

awaitpick 

await_stroke_2 

awaitstroke2 

begin_batch_of_updates 

beginbatchupdate 

close_retained_segment 

closeretainseg 

close temporary segment 

closetempseg 

create_retained_segment 

createretainseg 

create temporary segment 

Greatetempseg 

define color indices 

defcolorindices 

delete_all_retained_segments 

delallretainsegs 

delete_retained_segment 

delretainsegment 

deselect view_surface 

deselectvwsurf 

end_batch_of_updates 

endbat chupdat e 

file to raster 

filetoraster 

free raster 

freeraster 

get_mouse_state 

getmousestate 

get_raster 

getraster 

initialize_core 

initializecore 

initialize device 

initializedevice 

initialize__view__surface 

initializevwsurf 

inquire_char just 

inqcharjust 

inquire_charpath_2 

inqcharpath2 

inquire charpath 3 

inqcharpath3 

inquire charprecision 

inqcharprecision 

inquire charsize 

inqcharsize 

inquire charspace 

inqcharspace 

inquire_charup_2 

inqcharup2 

inquire charup 3 

inqcharup3 

inquire color indices 

inqcolorindices 

inquire current position 2 

inqcurrpos2 

inquire current_position 3 

inqcurrpos3 

inquire_detectability 

inqdetectability 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 


C Name 

Pascal Name 

inquire echo 

inqecho 

inquire_echo_position 

inqechoposition 

inquire echo surface 

inqechosurface 

inquire fill index 

inqfillindex 

inquire font 

inqfont 

inquire__highlighting 

inqhighlighting 

inquire image__transformation 2 

inqimgtransform2 

inquire__image_transformation_3 

inqimgtransform3 

inquire image transformation type 

inqimgx fo rmt ype 

inquire_image_translate_2 

inqimgtranslate2 

inquire image translate 3 

inqimgtranslate3 

i n qu i r e_i n v e r s e_c ompo sit e_mat r i x 

inqinvcompmatrix 

inquire_keyboard 

inqkeyboard 

inquire line index 

inqlineindex 

inquire linestyle 

inqlinestyle 

inquire linewidth 

inqlinewidth 

inquire_locator 2 

inqlocator2 

inquire marker symbol 

inqmarkersymbol 

i n qu i r e_n dc_sp a c e_2 

inqndcspace2 

inquire_ndc_space_3 

inqndcspaceS 

inquire open retained segment 

inqopenretainseg 

inquire open temporary segment 

inqopentempseg 

inquire_pen 

inqpen 

inquire_pick_id 

inqpickid 

inquire_jpolygon_edge_style 

inqpolyedgestyle 

inquire_polygon interior style 

inqpolyintrstyle 

inquire ^primitive attributes 

inqprimattribs 

inquire_projection 

inqprejection 

inquire_rasterop 

inqrasterop 

inquire retained segment names 

inqretainsegname 

inquire retained segment surfaces 

inqretainsegsurf 

inquire_segment_detect ability 

inqsegdetectable 

inquire segment highlighting 

inqseghighlight 

inquire_segment_image_trans format ion 2 

inqsegimgxform2 

inquire segment image transformation 3 

inqsegimgxform3 

inquire segment image transformation type 

inqsegimgxfrmtyp 

inquire_segment_image__translate__2 

inqsegimgxlate2 

inquire_segment_image translate 3 

inqsegimgxlate3 

inquire_segment__visibility 

inqsegvisibility 

inquire stroke 

inqstroke 

inquire_text_extent_2 

inqtextextent2 

inquire text extent 3 

inqtextextent3 

inquire_text_index 

inqtextindex 

inquire_valuator 

inqvaluator 

inquire view depth 

inqviewdepth 

inquire_view_jplane_distance 

inqviewplanedist 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 


C Name Pascal Name 


inquire view_plane normal 

inqviewplanenorm 

inquire view referencej>oint 

inqviewrefpoint 

inquire_view_up_2 

inqviewup2 

inquire view up 3 

inqviewup3 

inquire viewing control parameters 

inqvwgcntrlparms 

inquire viewing_parameters 

inqviewingparams 

inquire viewport 2 

inqviewport2 

inquire viewport 3 

inqviewport3 

inquire visibility 

inqvisibility 

inquire window 

inqwindow 

inquire worldcoordinate_matrix_2 

inqworldmatrix2 

inquire world coordinate matrix 3 

inqworldmatrix3 

line abs 2 

lineabs2 

line abs 3 

lineabs3 

line rel 2 

linerel2 

line rel 3 

linerel3 

map ndc to world 2 

mapndctoworld2 

map ndc to world 3 

mapndctoworld3 

map_wor ld_t o_ndc_2 

mapworldtondc2 

map_wor ld_t o_ndc_3 

mapworldtondc3 

marker abs 2 

markerabs2 

marker abs 3 

markerabs3 

marker rel 2 

markerrel2 

marker rel 3 

markerrel3 

move_abs_2 

moveabs2 

move_abs_3 

moveabs3 

move rel 2 

moverel2 

move rel 3 

moverel3 

new frame 

newframe 

polygon abs 2 

polygonabs2 

polygon_abs_3 

polygonabs3 

polygon_rel_2 

polygonrel2 

polygon_rel_3 

polygonrel3 

polyline abs 2 

polylineabs2 

polyline_abs_3 

polylineabs3 

polyline rel 2 

polylinerel2 

polyline rel 3 

polylinerel3 

polymarker_abs_2 

polymarkerabs2 

po lymar ke r_ab s_3 

polymarkerabs3 

polymarker rel 2 

polymarkerrel2 

polymarker rel 3 

polymarkerrel3 

print error 

printerror 

put_raster 

putraster 

raster__to_f ile 

rastertofile 

rename retained segment 

renameretainseg 

report most recent error 

reportrecenterr 

A su n 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 


C Name 

Pascal Name 

restore_segment 

restoresegment 

save_segment 

savesegment 

select___view___surf ace 

selectvwsurf 

s e t_ba c k__pl a ne___c 1 ippi n g 

setbackclip 

set_charjust 

setcharjust 

set charpath 2 

setcharpath2 

set_charpath_3 

setcharpath3 

set_charprecision 

setcharprecision 

set_charsize 

setcharsize 

set_charspace 

setcharspace 

set_chariip_2 

setcharup2 

set_charup_3 

setcharup3 

set_coordinate_system_type 

setcoordsystype 

set detectability 

setdetectability 

set_drag 

setdrag 

set_echo 

setecho 

set_echo_group 

s et e cho gr oup 

set_echo_position 

setechoposition 

set echo surface 

setechosurface 

s e t __f i 1 l__i n de X 

setfillindex 

set_font 

setfont 

set_front_plane_clipping 

setfrontclip 

set highlighting 

sethighlighting 

s e t__ima ge_t r a n s f o r ma t i o n_2 

setimgtransform2 

s e t_ima ge_t r an s f o rmat ion 3 

setimgtransform3 

set_image_transformation type 

setimgxformtype 

s e t_image_t r an s 1 at e_2 

setimgtranslate2 

s e t___image_t r an s 1 a t e_3 

setimgtranslate3 

set_keyboard 

setkeyboard 

s e t_light_dire ction 

setlightdirect 

set_line_index 

setlineindex 

set_linestyle 

setlinestyle 

set linewidth 

setlinewidth 

set_locator_2 

setlocator2 

set marker symbol 

setmarkersymbol 

^ ^ P ^ ^ 

setndcspace2 


setndcspace3 

set__output_clipping 

setoutputclip 

set j>en 

setpen 

set_pick 

setpick 

set j>ick_id 

setpickid 

set j>olygon_edge_style 

setpolyedgestyle 

set_polygon_interior__style 

setpolyintrstyle 

set_primitive_attributes 

setprimattribs 

s et_pr o j e c t ion 

setprojaction 

set_rasterop 

setrasterop 


O 
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Table E-3 Correspondence Between C Names and Pascal Names — Continued 



E.4. Type Declarations The list on the following pages is a complete alphabetical list of the Pascal data 

structures in SunCore. 

type iarr = array[1..256] of integer; 
type parr = array[1..256] of real; 
type cct - array[1..257] of char; 
type ivarray = array[1..4,1..4] of real; 
type ivarrayl = array[1..3,1..3] of real; 
type pttype = record 
X,y,z,w:real; 
end; 

type aspect = record 

width, height:real; 

# sun 
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end; 

type primattr = record 

lineindx: integer; 
fillindx: integer; 
textindx: integer; 
linestyl: integer; 
polyintstyl: integer; 
polyedgstyl: integer; 
linwidth: real; 
pen: integer; 
font: integer; 
charsize: aspect; 

chrup^ chrpath, chrspace: pttype; 
chjust: integer; 
chqualty: integer; 
marker: integer; 
pickid: integer; 
rasterop: integer; 
end; 

type rasttyp = record 

width: integer; 
height: integer; 
depth: integer; 
bits: integer; {var} 
end; 

type cmap = record 

typ: integer; 
nbyt: integer; 
dat :integer; {var} 
end; 

type windtype = record 

xmin, xmax, ymin^ ymax:real; 

end; 

type porttype = record 

xmin, xmax^ ymin, ymax, zmin, zmax: real; 

end; 

type vwprmtype = record 

vwrefpt: array [1..3] of real; 
vwplnorm: array [1..3] of real; 
viewdis:real; 
frontdis:real; 
backdis:real; 
projtype:integer; 
projdir: array [1..3] of real; 
window:windtype; 
vwupdir: array [1..3] of real; 
viewport:porttype; 
end; 

type vwsurf = record 

screenname: array [1..DEVNAMESIZE] of char; 
windowname: array [1..DEVNAMESIZE] of char; 
windowfd:integer; 
dd:integer; 
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instance:integer; 

^ cmapsize:integer; 

cmapname: array [1..DEVNAMESIZE] of char; 
flags:integer; 
ptr: integer; 

end; 

type vwsurfst = array [1..DEVNAMESIZE] of char; 
type vwarr = array[1-.MAXVSURF] of vwsurf; 

E.5. Function Declarations The list on the following pages is a complete alphabetical list of the Pascal func¬ 

tions in SunCore. 

function allocateraster(var rptr:rasttyp):integer; external; 

function awaitanybutton(tim:integer; var buttonnum:integer):integer; external; 
function awtbuttongetloc2(time:integer; locatornum:integer; 

var buttonnum:integer; var x:real; var y:real):integer; external; 
function awtbuttongetval(time:integer; valnum:integer; var buttonnum:integer; 
var val:real):integer; external; 

function awaitkeyboard(tim:integer; keynum:integer; var sptr:cct; 

var length:integer):integer; external; 
function awaitpick(time:integer; picknum:integer; var segnam:integer; 
var pickid:integer):integer; external; 

function awaitstroke2(tim:integer; picknum:integer; asize:integer; var x:parr; 

var y:parr; numxy:integer):integer; external; 
function beginbatchupdate:integer; external; 
function closeretainseg:integer; external; 
function closetempseg:integer; external; 

function createretainseg(segname:integer):integer; external; 
function createtempseg:integer; external; 

function defcolorindices(var surfacename:vwsurf; il:integer; i2:integer; 

var r:parr; var g:parr; var b:parr):integer; external; 
function delallretainsegs:integer; external; 

function de1retainsegment(segname:integer):integer; external; 
function deselectvwsurf(var surfacename:vwsurf):integer; external; 
function endbatchupdate:integer; external; 

function filetoraster(var rasfid:text; var rptr:rasttyp; var map:cmap) 

:integer; external; 

function freeraster(var rptr:rasttyp):integer; external; 

function getmbusestate(devclass:integer; devnum:integer; var x:real; 

var y:real; var buttons:integer):integer; external; 
function getraster(var surfacename:vwsurf; xmin:real; xmax:real; ymin:real; 

ymax:real; xd:integer; yd:integer; var rptr:rasttyp):integer; external; 
function getviewsurface(var surfacename:vwsurf):integer; external; 
function initializecore(outputlevel:integer; inputlevel:integer; 

dimension:integer):integer; external; 
function initializedevice(deviceclass:integer; devicenum:integer) 

:integer; external; 

function initializevwsurf(var surfacename:vwsurf; typ:integer) 

;integer; external; 

function inqcharjust(var chjust:integer):integer; external; 
function inqcharpath2(var x:real; var y:real):integer; external; 
function inqcharpathS(var x:real; var y:real; var z:real):integer; external; 
function inqcharprecision(var chquality:integer):integer; external; 
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function inqcharsize(var width:real; var height:real):integer; external; 
function inqcharspace(var space:real):integer; external; 
function inqcharup2(var x:real; var y:real):integer; external; 
function inqcharupS(var xrreal; var y:real; var z:real):integer; external; 
function inqcolorindices(var surfacename:vwsurf; iliinteger; i2:integer; 

var r:parr; var g;parr; var brparr):integer; external; 
function inqcurrpos2(var x:real; var y:real):integer; external; 
function inqcurrposS(var xireal; var y:real; var z:real):integer; external; 
function inqdetectability(var detect:integer):integer; external; 
function inqecho(devclass:integer; devnum:integer; var echotype:integer) 

:integer; external; 

function inqechoposition(devclass:integer; devnum:integer; var xrreal; 

var y:real):integer; external; 
function inqechosurface(devclass:integer; devnum:integer; 

var surfacename:vwsurf):integer; external; 
function inqfillindex(var color:integer):integer; external; 
function inqfont(var font:integer):integer; external; 
function inqhighlighting(var highlight:integer):integer; external; 
function inqimgtransform2(var sx:real; var sy:real; var a:real; var tx:real; 
var ty:real):integer; external; 

function inqimgtransformS(var sx:real; var sy:real; var sz:real; var ax:real; 
var ay:real; var az:real; var tx:real; var ty:real; var tz:real) 

:integer; external; 

function inqimgxformtype(var segtype:integer):integer; external; 
function inqimgtranslate2(var tx:real; var ty:real):integer; external; 
function inqimgtranslateS(var tx:real; var ty:real; var tz:real) 

:integer; external; 

function inqinvcompmatrix(var iarray:ivarray):integer; external; 
function inqkeyboard(keynum:integer; var bufsize:integer; var string:cct; 

var pos:integer):integer; external; 
function inqlineindex(var color:integer):integer; external; 
function inqlinestyle(var linestyle:integer):integer; external; 
function- inqlinewidth(var linewidth:real) :integer; external; 

function inqlocator2 (locniam:integer; var x:real; var y:real) :integer; external; 
function inqmarkersymbol(var mark:integer):integer; external; 
function inqndcspace2(var width:real; var height:real):integer; external; 
function inqndcspaceS(var width:real; var height:real; var depth:real) 

:integer; external; 

function inqopenretainseg(var segname:integer):integer; external; 
function inqopentempseg(var open:integer):integer; external; 
function inqpen(var pen:integer):integer; external; 
function inqpickid(var pick:integer):integer; external; 
function inqpolyedgestyle(var pestyle:integer):integer; external; 
function inqpolyintrstyle(var pistyle:integer):integer; external; 
function inqprimattribs(var defprim:primattr):integer; external; 
function inqprojection(var ptype:integer; var dx:real; var dy:real; 

var dz:real):integer; external; 
function inqrasterop(var rastop:integer):integer; external; 
function inqretainsegname(arraycnt:integer; var seglist:iarr; 

var segcnt:integer):integer; external; 
function inqretainsegsurf(segname:integer; arraycnt:integer; 

var surflist:vwarr; var surfcnt:integer):integer; external; 
function inqsegdetectable(segname:integer; var dtable:integer) 
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:integer; external; 

function inqseghighlight(segname:integer; var highlight:integer) 

:integer; external; 

function inqsegimgxform2(segname:integer; var sx:real; var sy:real; 

var a:real; var txireal; var tyireal):integer; external; 
function inqsegimgxformS(segname:integer; var sx:real; var sy:real; 
var szireal; var rxireal; var ry:real; var rzireal; var txireal; 
var tyireal; var tzireal)iinteger; external; 
function inqsegimgxfrmtyp(segnameiinteger; var segtypeiinteger) 

Iinteger; external; 

function inqsegimgxlate2(segnameiinteger; var txireal; var tyifeal) 

Iinteger; external; 

function inqsegimgxlateS(segnameiinteger; var sxireal; var syireal; 
var szI real) Iinteger; external; 

function inqsegvisibility(segnameiinteger; var visibleiinteger) 

Iinteger; external; 

function inqstroke(strokenumiinteger; var bufsizeiinteger; var distireal; 

var time Iinteger) iinteger; external; 
function inqtextextent2(var stringicct; var dxireal; var dyireal) 

Iinteger; external; 

function inqtextextentS(var stringicct; var dxireal; var dyireal; var dzireal) 
Iinteger; external; 

function inqtextindex(var coloriinteger)iinteger; external; 
function inqvaluator(valnumiinteger; var initireal; var lowireal; 
var high I real) Iinteger; external; 

function inqviewdepth(var fdistireal; var bdistireal)iinteger; external; 
function inqviewplanedist(var vdist:real)iinteger; external; 
function inqviewplanenorm(var dxireal; var dyireal; var dzireal) 

Iinteger; external; 

function inqviewrefpoint(var rxireal; var ryireal; var rzireal) 

Iinteger; external; 

function inqviewup2(var dxireal; var dyireal)iinteger; external; 

function inqviewup3(var dxireal; var dyireal; var dzireal)iinteger; external; 

function inqvwgcntrlparms(var wclipiinteger; var fclipiinteger; 

var belip Iinteger; var typiinteger) iinteger; external; 
function inqviewingparams(var viewparmivwprmtype)iinteger; external; 
function inqviewport2(var xminireal; var xmaxireal; var yminireal; 
var ymaxI real) Iinteger; external; 

function inqviewportS(var xminireal; var xmaxireal; var yminireal; 

var ymaxireal; var zminireal; var zmaxireal)iinteger; external; 
function inqvisibility(var visibleiinteger)iinteger; external; 
function inqwindow(var uminireal; var umaxireal; var vminireal; 

var vmaxireal)iinteger; external; 
function inqworldmatrix2(var iarrayiivarrayl)iinteger; external; 
function inqworldmatrixS(var iarrayiivarray)iinteger; external; 
function lineabs2(xireal; yireal)iinteger; external; 
function lineabsS(xireal; yireal; zireal)iinteger; external; 
function linerel2(xireal; yireal)iinteger; external; 
function linerelS(xireal; yireal; zireal)iinteger; external; 
function mapndctoworld2(ndxireal; ndyireal; var wldxireal; var wldyireal) 

Iinteger; external; 

function mapndctoworldS(ndxireal; ndyireal; ndzireal; var wldxireal; 
var wldyireal; var wldzireal)iinteger; external; 
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function mapworldtondc2(wldx:real; wldyrreal; var ndxtreal; var ndyireal) 

:integer; external; 

function mapworldtondcS(wldx:real; wldyireal; wldz:real; var ndx:real; 

var ndy:real; var ndz:real):integer; external; 
function inarkerabs2(mx:real; my:real):integer; external; 
function markerabs3(mx:real; my:real; mz:real):integer; external; 
function roarkerrel2(dx:real; dy:real):integer; external; 
function markerrelS(dx:real; dy:real; dz:real):integer; external; 
function moveabs2(x:real; y:real):integer; external; 
function moveabs3(x:real; y:real; z:real):integer; external; 
function moverel2(x:real; y:real):integer; external; 
function moverel3(x:real; y:real; z:real):integer; external; 
function newframe:integer; external; 

function pasloc(function f:integer):integer; external; 
function polygonabs2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polygonabs3(var xcoor:parr; var ycoor:parr; var zcoor:parr; n:integer) 
:integer; external; 

function polygonrel2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polygonrel3(var xcoor:parr; var ycoor:parr; var zcoor:parr; n:integer) 
:integer; external; 

function polylineabs2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polylineabs3(var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n:integer):integer; external; 

function polylinerel2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polylinerel3(var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n:integer):integer; external; 

function polymarkerabs2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polymarkerabs3(var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n:integer):integer; external; 

function polymarkerrel2(var xcoor:parr; var ycoor:parr; n:integer) 

:integer; external; 

function polymarkerrel3(var xcoor:parr; var ycoor:parr; var zcoor:parr; 
n:integer):integer; external; 

function printerror(var string:cct; error:integer):integer; external; 
function putraster(var rptr:rasttyp):integer; external; 
function puttext(var string:cct):integer; external; 

function rastertofile(var rptr:rasttyp; var map:cmap; var rasfid:text; 
n:integer):integer; external; 

function renameretainseg(segname:integer; newname:integer):integer; external; 

function reportrecenterr(var error:integer):integer; external; 

function restoresegment(segname:integer; var fname:cct):integer; external; 

function savesegment(segname:integer; var fname:cct):integer; external; 

function selectvwsurf(var surfacename:vwsurf):integer; external; 

function setbackclip(onoff:integer):integer; external; 

function setcharjust(ohjust:integer):integer; external; 

function setcharpath2 (dx:real; dy:real) :integer; extejtnal; 

function setcharpath3(dx:real; dy:real; dz:real):integer; external; 

function setcharprecision(chquality:integer):integer; external; 
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function setcharsize(chwid:real; chht:real):integer; external; 
function setcharspace(space:real):integer; external; 
function setcharup2(dx:real; dy:real):integer; external; 
function setcharup3(dx:real; dyireal; dz:real):integer; external; 
function setcoordsystype(typ:integer):integer; external; 
function setdetectability(detect:integer):integer; external; 
function setdrag(drag:integer):integer; external; 

function setecho(devclass:integer; devnum:integer; echotype:integer) 

:integer; external; 

function setechogroup(devclass:integer; var devarray:iarr; n:integer; 
echotype:integer):integer; external; 

function setechoposition(devclass:integer; devnum:integer; x:real; y:real) 

:integer; external; 

function setechosurface(devclass:integer; devnum:integer; 

var surfacename:vwsurf):integer; external; 
function setfillindex(color:integer):integer; external; 
function setfont(font:integer):integer; external; 
function setfrontclip(onoff:integer):integer; external; 
function sethighlighting(highlight:integer):integer; external; 
function setimgtransform2(sx:real; sy:real; a:real; tx:real; ty:real) 

:integer; external; 

function setimgtransform3(sx:real; sy:real; sz:real; ax:real; ay:real; az:real; 

tx:real; ty:real; tz:real):integer; external; 
function setimgxformtype(segtype:integer):integer; external; 
function setimgtranslate2(tx:real; ty:real):integer; external; 
function setimgtranslate3(tx:real; ty:real; tz:real):integer; external; 
function setkeyboard(keynum:integer; bufsize:integer; var string:cct; 
pos:integer):integer; external; 

function setlightdirect(dx:real; dy:real; dz :real) :integer; external; 
function setlineindex(color:integer):integer; external; 
function setlinestyle(style:integer):integer; external; 
function setlinewidth(width:real):integer; external; 

function setlocator2(locnum:integer; x:real; y:real):integer; external; 

function setmarkersymbol(mark:integer):integer; external; 

function setndcspace2(width:real; height:real):integer; external; 

function setndcspace3(width:real; height:real; depth:real):integer; external; 

function setoutputclip(onoff:integer):integer; external; 

function setpen(pen:integer):integer; external; 

function setpick(pickid:integer; aperture:real):integer; external; 
function setpickid(pickid:integer):integer; external; 
function setpolyedgestyle(pestyle:integer):integer; external; 
function setpolyintrstyle(pistyle:integer):integer; external; 
function setprimattribs(var defprim:primattr):integer; external; 
function setprojection(ptype:integer; dx:real; dy:real; dz:real) 

:integer; external; 

function setrasterop(rop:integer):integer; external; 

function setsegdetectable(segname:integer; detectbl:integer):integer; external; 
function setseghighlight(segname:integer; highlight:integer):integer; external; 
function setsegimgxform2(segname:integer; sx:real; sy:real; a:real; tx:real; 
ty:real):integer; external; 

function setsegimgxform3(segname:integer; sx:real; sy:real; sz:real; rx:real; 

ry:real; rz:real; tx:real; ty:real; tz:real):integer; external; 
function setsegimgxlate2(segname:integer; tx:real; ty:real):integer; external; 
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function setsegimgxlateS(segname:integer; txrreal; ty:real; tz:real) 

:integer; external; 

function setsegvisibility(segname:integer; visible:integer):integer; external; 
function setshadingparams(amb:real; difrreal; spec:real; floodrreal; bumpireal; 

hue:integer; style:integer):integer; external; 
function setstroke(strokenum:integer; bufsize:integer; distrreal; time:integer) 
:integer; external; 

function settextindex(color:integer):integer; external; 

function setvaluator(valnum:integer; initireal; low:real; high:real):integer; 
external; 

function setvertexindices(var x:iarr; n:integer):integer; external; 
function setvertexnormals(var xcoor:parr; var ycoortparr; var zcoor:parr; 
n:integer):integer; external; 

function setviewdepth(near:real; far:real):integer; external; 
function setviewplanedist(dist:real):integer; external; 

function setviewplanenorm(dx:real; dy:real; dz:real):integer; external; 
function setviewrefpoint(x:real; y:real; z:real):integer; external; 
function setviewup2(dx:real; dy:real):integer; external; 
function setviewupS(dx:real; dy:real; dz:real):integer; external; 
function setviewingparams(var viewparm:vwprmtype):integer; external; 
function setviewport2(xmin:real; xmax:real; ymin:real; ymax:real) 

:integer; external; 

function setviewport3(xmin:real; xmax:real; ymin:real; ymax:real; zmin:real; 
zmax:real):integer; external; 

function setvisibility(visibility:integer):integer; external; 
function setwindow(umin:real; umax:real; vminrreal; vmax:real) 

:integer; external; 

function setwindowclip(onoff:integer):integer; external; 
function setworldmatrix2(var iarray:ivarrayl):integer; external; 
function setworldmatrix3(var iarray:ivarray):integer; external; 
function setzbuffercut(var surfacename:vwsurf; var x:parr; var z:parr; 
n:integer):integer; external; 

function sizeraster(var surfacename:vwsurf; xmin:real; xmaxireal; ymin:real; 

ymax:real; var rptr:rasttyp):integer; external; 
function terminatecore:integer; external; 

function terminatedevice(devclass:integer; devnum:integer):integer; external; 
function terminatevwsurf(var surfacename:vwsurf):integer; external; 

Note: since vwarr is an array of MAXVSURF viewsurfaces, arraycnt should be MAXVSURF. 

function inqsegdetectable(segname:integer;var dtable:integer) 

:integer; external; 

function inqseghighlight(segname:integer;var highlight:integer) 

:integer; external; 

function inqsegimgxform2(segname:integer;var sx:real;var syireal; 
var a:real;var tx:real;var tyrreal 
):integer; external; 

function inqsegimgxform3(segname:integer;var sx:real;var sy:real; 
var sz:real;var rx:real;var ry:real; 
var rz:real;var tx:real;var ty:real;var tz:real 
):integer; external; 

function inqsegimgxfrmtyp(segname:integer;var segtype:integer) 

:integer; external; 

function inqsegimgxlate2(segname:integer;var tx:real;var tyireal) 
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:integer; external; 

function inqsegimgxlate3(segname:integer;var sx:real;var syrreal; 
var sz:real):integer; external; 

function inqsegvisibility(segname:integer;var visible:integer): 
integer; external; 

function inqstroke(strokenum:integer;var bufsize:integer;var 
dist:real;var time:integer):integer; external; 
function inqtextextent2(var string:cct;var dxireal; var dyireal 
):integer; external; 

function inqtextextentS(var stringrcct;var dxrreal; var dyrreal 
; var dz:real):integer; external; 
function inqtextindex(var color:integer):integer; external; 

function inqvaluator(valnum:integer;var init:real;var low:real;var high:real) 

:integer; external; 

function inqviewdepth(var fdist:real;var bdistzreal) 

:integer; external; 

function inqviewplanedist(var vdist:real):integer; external; 
function inqviewplanenorm(var dx:real; var dy:real; 

var dz:real):integer; external; 
function inqviewrefpoint(var rxireal; var ry:real; 

var rz:real):integer; external; 
function inqviewup2(var dxrreal; var dyrreal 
):integer; external; 

function inqviewupS(var dxrreal; var dyrreal; 

var dzrreal)rinteger; external; 

function inqvwgcntrlparms(var wcliprinteger;var fcliprinteger; 
var bcliprinteger;var typrinteger) 
rinteger; external; 

function inqviewingparams(var viewparmrvwprmtype)rinteger; external; 
function inqviewport2(var xminrreal; var xmaxrreal;var yminrreal;var ymaxrreal 
)rinteger; external; 

function inqviewportS(var xminrreal; var xmax:real;var ymin:real;var ymax:real 
;var zmin:real;var zmaxrreal) 

:integer; external; 

function inqvisibility(var visible:integer) 

:integer; external; 

function inqwindow(var uminireal; var umax:real;var vmin:real;var vmaxrreal 
):integer; external; 

function inqworldmatrix2(var iarray:ivarrayl):integer; external; 
function inqworldmatrixS(var iarray:ivarray):integer; external; 
function lineabs2(x:real;y:real)rinteger; external; 
function lineabs3(x:real;y:real;z:real)rinteger; external; 
function linerel2(x:real;y:real):integer; external; 
function linerel3(x:real;y:real;z:real):integer; external; 
function mapndctoworld2(ndx:real; ndy:real; 

var wldx:real; var wldy:real) 
rinteger; external; 

function mapndctoworld3(ndx:real; ndyrreal; ndzrreal; 

var wldxrreal; var wldyrreal 
; var wldzrreal) 
rinteger; external; 

function mapworldtondc2(wldx:real; wldyrreal; 

var ndx:real; var ndyrreal) 
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:integer; external; 

function mapworldtondc3(wldx:real; wldyrreal; wldzrreal; 
var ndxrreal; var ndyrreal 
; var ndzrreal 
):integer; external; 

function markerabs2(mx:real;my:real):integer; external; 
function markerabsS(mx:real; my:real;mz:real):integer; external; 
function markerrel2(dx:real;dy:real)rinteger; external; 
function markerrelS(dx:real; dy:real;dz:real):integer; external; 
function moveabs2(x:real;y:real):integer; external; 
function moveabsS(x:real;y:real;z:real):integer; external; 
function moverel2(x:real;y:real):integer; external; 
function moverelS(x:real;y:real;z:real):integer; external; 
function newframe:integer; external; 
function pasloc(function f:integer 
):integer; external; 

function polygonabs2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polygonabsS(var xcoor:parr; var ycoor:parr;var zcoor:parr; 

n:integer):integer; external; 
function polygonrel2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polygonrel3(var xcoor:parr; var ycoor:parr;var zcoor:parr; 

n:integer):integer; external; 
function polylineabs2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polylineabs3(var xcoor:parr; var ycoor:parr;var zcoor:parr; 

n:integer):integer; external; 
function polylinerel2(var xcoor:parr;var ycoor:parr; 
n:integer):integer; external; 

function polylinerel3(var xcoor:parr; var ycoor:parr;var zcoor:parr; 

n:integer):integer; external; 
function polymarkerabs2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polymarkerabs3 (var xcoor:parr; var ycoor:parr;var zcoor:parr; 

n:integer):integer; external; 
function polymarkerrel2(var xcoor:parr; var ycoor:parr; 
n:integer):integer; external; 

function polymarkerrel3(var xcoor:parr; var ycoor:parr;var zcoor:parr; 
n:integer):integer; external; 

function printerror(var string:cct;error:integer):integer; external; 
function putraster(var rptr:rasttyp):integer; external; 
function puttext(var string:cct):integer; external; 

function rastertofile(var rptr:rasttyp;var map:cmap;rasfid:integer 
):integer; external; 

function renameretainseg(segname:integer;newname:integer):integer; external; 
function reportrecenterr(var error:integer):integer; external; 
function restoresegment(segname:integer;var fname:cct):integer; external; 
function savesegment(segname:integer;var fname:cct):integer; external; 
function selectvwsurf(surfacename:vwsurf 
):integer; external; 

function setbackclip(onoff:integer):integer; external; 
function setcharjust(chjust:integer):integer; external; 
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function setcharpath2(dx:real; dy:real):integer; external; 
function setcharpathS(dx:real; dy:real;dz;real)rinteger; external; 
function setcharprecision(chquality:integer):integer; external; 
function setcharsize(chwid:real;chht:real):integer; external; 
function setcharspace(space:real):integer; external; 
function setcharup2(dx:real; dy:real):integer; external; 
function setcharup3(dx:real; dy:real;dz:real);integer; external; 
function setcoordsystype(typ:integer):integer; external; 
function setdetectability(detect:integer):integer; external; 
function setdrag(drag:integer):integer; external; 
function setecho(devclass:integer;devnum:integer; 

echotype:integer):integer; external; 
function setechogroup(devclass:integer;var devarray:iarr;n:integer; 

echotype:integer):integer; external; 
function setechoposition(devclass:integer;devnum:integer; 

x:real;y:real):integer; external; 
function setechosurface(devclass:integer;devnum:integer; 

surfacename:vwsurf):integer; external; 
function setfillindex(color:integer):integer; external; 
function setfont(font:integer):integer; external; 
function setfrontclip(onoff:integer):integer; external; 
function sethighlighting(highlight:integer):integer; external; 
function setimgtransform2(sx:real; sy:real;a:real 

;tx:real; ty:real):integer; external; 
function setimgtransform3(sx:real; sy:real;sz:real; 
ax:real; ay:real;az:real; 
tx:real; ty:real;tz:real) 

:integer; external; 

function setimgxformtype(segtype:integer):integer; external; 
function setimgtranslate2(tx:real; ty:real):integer; external; 
function setimgtranslate3(tx:real; ty:real;tz:real):integer; external; 
function setkeyboard(keynum:integer;bufsize:integer;var string:cct; 

pos:integer):integer; external; 
function setlightdirect(dx:real; dy:real;dz:real 
):integer; external; 

function setlineindex(color:integer):integer; external; 
function setlinestyle(style:integer):integer; external; 
function setlinewidth(width:real):integer; external; 

function setlocator2(locnum:integer;x:real;y:real):integer; external; 
function setmarkersymbol(mark:integer):integer; external; 
function setndcspace2(width:real;height:real):integer; external; 
function setndcspace3(width:real;height:real;depth:real) 

:integer; external; 

function setoutputclip(onoff:integer):integer; external; 
function setpen(pen:integer):integer; external; 

function setpick(picknum:integer; aperture: real):integer; external; 
function setpickid(pickid:integer):integer; external; 
function setpolyedgestyle(pestyle:integer):integer; external; 
function setpolyintrstyle(pistyle:integer):integer; external; 
function setprimattribs(var defprim:primattr):integer; external; 
function setprojection(ptype:integer;dx:real; dy:real;dz:real) 

:integer; external; 

function setrasterop(rop:integer):integer; external; 


sun 

microsystems 


Revision A, of 9 May 1988 




194 SunCore Reference Manual 


function setsegdetectable(segname:integer; detectbl:integer) 

:integer; external; 

function setseghighlight(segname:integer; highlight:integer) 

:integer; external; 

function setsegimgxform2(segname:integer;sx:real; sy:real;a;real; 

tx:real;ty:real)linteger; external; 
function setsegimgxformS(segname:integer; sx:real; sy:real; 

sz:real; rxrreal; ry:real; rz:real 
; txrreal; tyrreal; tzrreal 
):integer; external; 

function setsegimgxlate2(segname;integer;tx:real; tyrreal 
)linteger; external; 

function setsegimgxlateS(segname:integer;tx:real; ty:real;tz:real 
):integer; external; 

function setsegvisibility(segname:integer;visible:integer):integer; external; 
function setshadingparams(amb:real;dif:real;spec:real;flood:real; 
bump:real;hue:integer;style:integer 
):integer; external; 

function setstroke(strokenum:integer;bufsize:integer; 
dist:real;time:integer) 

:integer; external; 

function settextindex(color:integer):integer; external; 
function setvaluator(valnum:integer;init:real;low:real;high:real) 

:integer; external; 

function setvertexindices(var x:iarr;n:integer):integer; external; 
function setvertexnormals(var xcoor:parr; var ycoor:parr;var zcoor:parr; 
n:integer):integer; external; 

function setviewdepth(near:real;far:real):integer; external; 
function setviewplanedist(dist:real):integer; external; 
function setviewplanenorm(dx:real; dy:real;dz:real):integer; external; 
function setviewrefpoint(x:real; y:real;z:real):integer; external; 
function setviewup2(dx:real; dy:real):integer; external; 
function setviewupS(dx:real; dy:real;dz:real):integer; external; 
function setviewingparams(var viewparm:vwprratype):integer; external; 
function setviewport2(xmin:real;xmax:real;ymin:real;ymax:real): 
integer; external; 

function setviewport3(xmin:real;xmax:real;ymin:real;ymax:real;zmin:real;zmax:real) 
:integer; external; 

function setvisibility(visibility:integer):integer; external; 
function setwindow(umin:real;Umax:real;vmin:real;vmax:real) 

:integer; external; 

function setwindowclip(onoff:integer):integer; external; 
function setworldmatrix2(var iarray:ivarrayl):integer; external; 
function setworldmatrixS(var iarray:ivarray):integer; external; 
function setzbuffercut(var surfacename:vwsurf;var x:parr; 

var z:parr;n:integer):integer; external; 
function sizeraster(var surfacename:vwsurf; 

xmin:real;xmax:real;ymin:real;ymax:real; 
var rptr:rasttyp):integer; external; 
function terminatecore:integer; external; 

function terminatedevice(devclass:integer;devnum:integer):integer; external; 
function terminatevwsurf(var surfacename:vwsurf):integer; external; 
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Hardware Floating Point SunCore 

Libraries 


SunCore programs intended for Sun workstations with hardware floating point 
support may use alternative SunCore libraries which provide higher floating 
point performance. Separate lihraries are provided for each of the floating point 
options described below. 

The presence of one of these options is independent of whether a Graphics Pro¬ 
cessor is present. It is not necessary to use one of these special libraries to take 
advantage of the Graphics Processor. 

For Sun-2 workstations, the only available floating point hardware is the SKY 
floating point processor. The appropriate library in this case is 
/usr/lib/libcoresky. a. A program linked with this library will only run 
on a Sun workstation with a SKY board. 

For Sun-3 workstations, two floating point hardware options are available. For 
Sun workstations with the MC68881 floating point co-processor, the appropriate 
library is /usr/lib/libcore68881. a. A program linked with this library 
will only mn on a Sun workstation with an MC68881. For Sun workstations 
with a Floating Point Accelerator (FPA), the appropriate library is 
/usr/lib/libcorefpa. a. A program linked with this library will only run 
on a Sun workstation with an FPA. 

C programs written with SunCore can be compiled with the following command 
line: 

% cc -txxx -o box box.c -Icorexxx -Isunwindow -Ipixrect -Im 
_ / 


FORTRAN programs written with SunCore can be compiled with the following 
command line: 

% til -txxx -o box box.f -lcore77 “Icorexxr -Isunwindow -Ipixrect -Im 
V_^^ 


Pascal programs written with SunCore can be compiled with the following com¬ 
mand line: 



In these command lines, xxx should be replaced with the appropriate symbol 
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from Table F-1. 

Table F-1 Floating Point Libraries 


Symbol 

Description 

sky 

Sky floating point board 

68881 

MC68881 floating point co-processor 

fpa 

Floating Point Accelerator 



If compiling and linking are done in separate steps, the -txxx option must be 
specified in the linking stage. The -fxcx: option may also be used in the compil¬ 
ing step. Different modules within a program cannot be compiled with different 
hardware floating point switches, but modules compiled with -fsoftor- 
f switch can be combined with modules compiled with a single type of 
hardware switch. See the manual pages for cc(l), f 77(1) and pc(l) for details. 

To compile and link a program to mn on any configuration of hardware for a 
specific processor type (Sun-2 or Sun-3), use the -f switch option for compil¬ 
ing and linking. The -f switch option will cause the compiler to take advan¬ 
tage of floating point hardware if it is available. Otherwise, the compiler will 
emulate this floating point support with software. See cc(l), f 77(1) or pc(l) 
for details. The -Icore option links with the generic SunCore library, 
/usr/lib/libsuncore.a. Note that different binary versions of a program 
are required for Sun-2 and Sun-3 processors. 

Many graphics programs written in C do not require the precision implied by w 
evaluating floating point expressions in double precision. The -f single 
option may be used to force single precision evaluation of arithmetic expressions 
involving only float quantities (see cc(l)). 
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Error Messages 














Error Messages 


SunCore does not use the error numbers suggested by the ACM CORE standard. 
The following table matches an error number with the error message: 




Table G-1 SunCore Error Messages 


Error 

Number 


Description 


0 The CORE SYSTEM has already been initialized. 

1 The specified level cannot be supported. 

2 The surface has already been initialized. 

3 No physical surface is associated with the specified logical sur¬ 
face. 

4 The CORE SYSTEM has not been initialized. 

5 The specified surface has not been initialized. 

6 The specified surface is already selected. 

7 The specified surface was not selected. 

8 A segment is open. 

9 The specified surface is not selected. 

10 The specified surface has not been deselected. 

11 This function has already been called once. 

12 A segment has been opened. 

13 A value specified for a default attribute is improper. 

14 The specified segment does not exist. 

15 The VIEW SURFACE ARRAY is not large enough. 

16 Segment list overflow^ can't create segment. 

17 There has been no 'end batch' since last 'begin batch'. 

18 There has been no corresponding 'begin batch'. 

19 A viewing function has been invoked, or a segment has been 
created. 

20 The value for TYPE is improper. 

21 No segment is open. 

22 n is <= 0. 

23 String contains an illegal character. 

24 The vectors established by CHARSPACE and CHARUP are parallel. 

25 Invalid marker table offset. 

26 Invocation when no open segment. 

27 Invalid attribute value. 
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Table G-1 SunCore Error Messages — Continued 


Error 

Number 


28 

29 

30 

31 

32 



Invalid segment type. 

Invalid segment number. 

Invalid image transformation for the segment. 

A retained segment named SEGNAME already exists. 

The segment type is inconsistent with the current 
IMAGE_TRANSFORM. 

No view surface is currently selected. 

The current viewing specification is inconsistent. 

No view surfaces have been initialized. 

There is an existing retained segment named NEW_NAME. 

There is no retained segment named SEGMENT^NAME. 

No characters in string (n=0). 

Dx^ dy, and dz, are all zero: no direction can be established. 
MIN is not less than MAX, for u or v bounds. 

FRONT_DISTANCE exceeds BACK_DISTANCE; back clip plane is in 
front. 

'ndcsp2' or 'ndcspS' has been invoked since SunCore was last ini¬ 
tialized. 

The invocation of 'ndcspx' is too late, default values have been 
assumed. 

A parameter value is greater than 1, or is less than or equal to 

0 . 

Neither parameter has a value of 1. 

Viewport extent is outside of normalized device coordinate space. 
MIN is not less than MAX, for x, y, or z bounds. 

Specified device already enabled. 

DEVICE_CLASS or DEVICE_NUM invalid. 

DEVICE_CLASS invalid. 

Specified device is not enabled. 

LOCATOR_NUM is invalid. 

The specified LOCATOR device is not enabled. 

VALUATOR_NUM is invalid. 

The specified VALUATOR device is not enabled. 

The TIME value is less than zero. 

EVENT_CLASS and EVENT^NUM do not specify a valid event device. 
EVENT_CLASS is not a legal event device class. 

The specified association already exists. 

EVENT_CLASS or SAMPLED_CLASS reference invalid or wrong type of 
class. 

EVENT_NUM or SAMPLED_NUM are invalid device numbers for their 
classes. 

The specified association does not exists. 

The current event report is not from a PICK device. 

The current event report is not from a KEYBOARD event. 
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Error 

Number 


65 


Table G-1 SunCore Error Messages — Continued 



Input string was not large enough to hold the string centered by 


When event occurred^ the LOCATOR device was not enabled or was 
not associated with the event device. 

When event occurred, the VALUATOR device was not enabled or was 
not associated with the event device. 

XECHO and YECHO specify positions outside NDC space. 

PICK_NUM does not specify a valid PICK device. 

LOCATOR_NUM does not specify a valid LOCATOR device. 

XLOC,YLOC specify a position outside normalized device coordinate 
space. 

VALUATOR_NUM is not a valid VALUATOR device. 

LOW_VALUE is greater than HIGH_VLAUE. 

INITIAL_VALUE lies outside the range defined by LOW_VALUE and 
HIGH_VALUE. 

KEYBOARD_NUM is not a valid KEYBOARD device. 

BUFFER_SIZE is <= zero or > the defined maximum. 

BUTTON_NUM is not a valid BUTTON device. 

Incorrect arguments for the specified function. 

Incorrect argument count for the specified function. 

Specified function not supported. 

More than MAXPOLY vertices in polygon. 

Invalid Viewing Specification. Viewing Matrix Unchanged! 

Invalid view surface name. 

Selected view surface cannot support hidden surfaces. 

No other view surface can be initialized at this time. 

Raster depth is 1 or 8 bit pixels only. 

Unable to allocate space for virtual memory display list. 

Memory allocation failure. 

Error in view reference point. 

Error in view plane normal. 

Error in view plane distance. 

Error in view depth. 

Error in projection. 

Error in window. 

Error in view up direction. 

Error in viewport. 

Set_ndc_space_2 or set_ndc_space_3 has already been invoked. 

The default NDC space has already been established. 

A parameter is not in the range of 0 to 1. 

Neither width nor height has a value of 1. 

Width or height is 0. 

STROKE_NUM is not a valid STROKE device. 

Input device is already initialized. 

Input device is not initialized. 
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Table G-1 SunCore Error Messages — Continued 


Error 

Number 


Description 


105 DEVICE_CLASS is not a valid device class. 

106 Invalid echo type for PICK device, 

107 Invalid echo type for KEYBOARD device, 

108 Invalid echo type for STROKE device. 

109 Invalid echo type for LOCATOR device. 

110 Invalid echo type for VALUATOR device. 

111 Invalid echo type for BUTTON device. 

112 Echo position specified is outside NDC space. 

113 No BUTTON device is initialized. 

114 Invalid raster type. 

115 Fewer than 3 vertices in polygon. 
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Type and Structure Definitions 


This appendix lists the types and stractures used by SunCore functions. The 
definition of these types and structures can be found in <usercore. h>. 


f - 

#define 

BASIC 

0 

/* Core output levels */ 


.^ 

#define 

BUFFERED 

1 




#define 

BUTTON 

2 




#define 

CENTER 

2 




#define 

CHARACTER 

1 




#define 

CMR 4 





#define 

CMRBOLD 

5 




#define 

COMPLETE 

2 




#define 

CONSTANT 

0 

/* polygon shading inodes */ 



#define 

DASHED 

2 




fdefine 

DEFAULT_VWSURF(ddname) 0, ddname, 0, 0, 

0, 0} 


#define 

DEVNAMESIZE 

20 




#define 

DOTDASHED 

3 




#define 

DOTTED 

1 




#define 

DYNAMICA 

2 




#define 

DYNAMICB 

3 




#define 

DYNAMICC 

4 




#define 

FALSE 

0 




#define 

GACHA 

1 




#define 

GACHABOLD 

3 




#define 

GALLANT 

0 

/* raster font constants */ 



♦define 

GOURAUD 

1 




♦define 

GREEK 

1 




♦define 

KEYBOARD 

1 




♦define 

LEFT 

1 




♦define 

LOCATOR 

3 




♦define 

MAXVSURF 

5 

/* view surfaces; maximum number 

of */ 


♦define 

NOINPUT 

0 

/* Core input levels */ 



♦define 

NONE 

1 

/* segment types */ 



♦define 

NORMAL 

0 

/* rasterop selection */ 



♦define 

NULL_VWSURF 

1 If 11 

, 0, 0, 0, 0, 0, 0} 



♦define 

OFF 0 

/* 

char justify constants */ 



♦define 

OLDENGLISH 

3 




♦define 

ORROP 

2 




♦define 

PARALLEL 

0 

/* transform constants */ 



♦define 

PERSPECTIVE 

1 




♦define 

PHONG 

2 
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#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 
#define 


PLAIN 0 
RIGHT 3 
ROMAN 0 
SAIL 2 
SCRIPT 2 
SHADED 1 
SOLID 0 
STICK 4 
STRING 0 
STROKE 5 
SYMBOLS 5 
SYNCHRONOUS 1 
THREED 1 
TRUE 1 
TWOD 0 
VALUATOR 4 
VWSURF_NEWFLG 
XFORM2 3 
XFORM3 3 
XLATE2 2 
XLATE3 2 
XORROP 1 


/* input device constants */ 

/* polygon interior style */ 

/* vector font select constants */ 


/* line styles */ 


/* Core dimensions */ 


static struct { /* default primitive attributes */ 

int lineindx; 
int fillindx; 
int textindx; 
int linestyl; 
int polyintstyl; 
int polyedgstyl; 
float linwidth; 
int pen; 
int font; 

float chwidth,chheight; 

float chup[4], chpath[4]^ chspace[4]; 

int chjust; 

int chqualty; 

int marker; 

int pickid; 

int rasterop; 

} PRIMATTS = {1,1,1,SOLID,PLAIN,SOLID,0.0,0^STICK,11.^11., 

{ 0 ., 1 ., 0 ., 1 .},{ 1 ., 0 ., 0 ., 1 .}, { 0 ., 0 ., 0 ., 1 .}, 

OFF,STRING,42,0,NORMAL}; 

struct vwsurf { 

char screenname[DEVNAMESIZE]; 

char windowname[DEVNAMESIZE]; 

int windowfd; 

int (*dd)(); 

int instance; 

int cmapsize; 

char cmapname[DEVNAMESIZE]; 
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Example Program. 213 


1.1. Declarations and the Main Program. 213 

1.2. The Factory Drawing Function. 216 

1.3. The Workstation Drawing Function. 217 

1.4. The Chip Drawing Function. 217 

1.5. The Cloud Drawing Function. 218 
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Example Program 


This appendix contains an example program that uses a number of SunCore's 
facilities. The example is called factory. It displays a factory building with a 
smokestack and a cloud of smoke puffing out Silicon chips move in at one end 
of the building, and Sun Workstations come out of the other end. 

Facilities displayed by this simple example include texturing, translation, scaling, 
and output clipping. The example is presented function by function, with an 
accompanying narrative. 

1.1. Declarations and the The first line in a SunCore application program should include the file 

Main Program <usercore.h> which contains the definitions required for using the SunCore 

graphics package. The factory program also has some definitions stored in 
the file factory. h. 


Figure I-l factory. h Header File 


#define 
#define 

FACTORY 10 

CLOUD 9 


\ 

#define 

WORKSTATION_l 

1 


#define 

WORKSTATION 2 

2 


fdefine 
#define 
♦define 
♦define 

V_ 

WORKSTATION_3 
CHIP_1 4 
CHIP_2 5 
CHIP_3 6 

3 

-. j 


Then there are some definitions. Then we define and initialize the variables that 
describe the outlines of the various objects in the picture: Then we have the main 
program: The first call in the program is to initialize SunCore, with an appropri¬ 
ate exit if there is an error returned: Then we initialize and select a view surface. 
Again, we exit if there was an error returned: Then we establish a viewport and a 
window. Note that we can set clipping on output — this is a SunCore extension 
to the ACM Core. Set up the color lookup table. Now make a temporary seg¬ 
ment for a title and border. Next we establish a segment for the factory. This 
segment is the simplest type, since we perform no transformations of any kind on 
it Next we establish a segment for the cloud above the factory. This segment is 
subject to scaling, so we must allow for transformations. Lastly, we establish 
segments for the chips and the workstations. The chips and workstations will be 
moving across the picture, so these segments must allow translation. Notice that 
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we created the workstations all on top of each other, and also all the chips on top 
of each other. The actual spatial separation of the individual segments is handled 
in the main body of the animation code. 

Now we get to the body of the code which animates the picture. The outer for 
loop is done 100 times. The calls on the translation functions make the chips and 
workstations move. The inner for loop makes the cloud grow: Finally, when 
everything is done, we deselect the view surface, and terminate SunCore: The 
remainder of the demonstration program consists of the functions which fill in 
the details in the individual segments. 


Figure 1-2 main. c Function 


#include <usercore.h> 

#include "factory.h" 

static float delta[] = {0.0^ 0.025, 2*0.025, 3*0.025, 4*0.025, 

5*0.025, 6*0.025, 7*0.025, 8*0.025, 9*0.025, 
10*0.025, 11*0.025, 12*0.025}; 
int pixwinddO; /* device driver name for SunWindows */ 

/* on a monochrome display - see Appendix B */ 
struct vwsurf vsurf = DEFAULT__VWSURF (pixwindd) ; 

/* The DEFAULT_VWSURF macro */ 

/* is defined in <usercore.h> */ 

main() 

{ 

short i, pO, pi, p2; 
float clx, cly, scale; 

if (initialize_core(DYNAMICB, NOINPUT, TWOD)) 
exit(0); 

if (initialize_view_surface(&vsurf, FALSE)) 
exit(1); 

if (select_view_surface(&vsurf)) 
exit(1); 

set_viewport_2(0.05, 0.95, 0.05, 0.7); 
set_window(30.0, 225.0, 30.0, 225.0); 
set_output_clipping(TRUE); 
set_window_clipping(FALSE); 
create_temporary_segment () ; 
move__abs__2 (30.0, 30.0); 
line__rel__2 (0.0, 195.0); 
line_rel_2 (195.0, 0.0); 
line_rel_2(0.0, -195.0); 
line_rel_2 (-195.0, 0.0); 
set_charprecision(CHARACTER); 
set_charsize(14.0, 14.0); 
set_text__index (1) ; 
move_abs_2 (40.0, 200.0); 
text("SunCore”); 
close__temporary_segment () ; 
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set_image_transformation__type (NONE) ; 
create_retained_seginent (FACTORY) ; 
factory(110.0, 60.0); 
close_retained_segment(); 
set_image_transformation_type (XFORM2) ; 
create_retained_segment (CLOUD) ; 
map_world_to_ndc_2(120.0, 100.0, &clx, &cly); 
set_segment_image_transformation_2 (CLOUD, 0.05, 0.1, 

0.0, clx, cly + 0.02); 
cloud(0.0, 0.0); 
close_retained_seginent 0 ; 
set_image_transformation_type (XLATE2) ; 

/* Draw the Sun Workstation Segment */ 
create_retained_segment (WORKSTATION^!) ; 
sunws(160.0, 60.0); 
close_retained_segment(); 
create_retained_segment (WORKSTATION_2) ; 
sunws(160.0, 60.0); 
close_retained_segment () ; 
create_retained_segment (WORKSTATION'S) ; 
sunws(160.0, 60.0); 
close_retained__segment () ; 

/* Draw the Chip Segment */ 
create_retained_segment (CHIP__1) ; 
chip(20.0, 70.0); 
close_retained_segment () ; 
create_retained_segment (CHIP_2) ; 
chip(20.0, 70.0); 
close_retained_segment () ; 
create_retained_segment (CHIP_3) ; 
chip(20.0, 70.0); 
close_retained_segment () ; 
pO = O^- 
pl = 4; 

p2 = 8; 

for (i=0; i<100; i++) { 

set_segment_image__translate_2 (WORKSTATION__l, delta [pO], 0.0); 
set__segment_image_translate__2 (WORKSTATION_2, delta [pi], 0.0); 
set_segment_image_translate_2 (WORKSTATION'S, delta [p2], 0.0); 
set_segment_image__translate_2 (CHIP_S, delta [p2], 0.0); 
set_segment_image_translate_2 (CHIP_2, delta [pi], 0.0); 
set_segment_image_translate_2 (CHIP_1, delta [pO], 0.0); 

p0++; 

pl++; 

p2++; 

if (pO > 11) 
pO = 0; 
if (pi > 11) 
pi = 0; 
if (p2 > 11) 

p2 = 0; 

for (scale=0.1; scale<1.0; scale += 0.2) 

set__segment__image_transformation_2 (CLOUD, 



Revision A, of 9 May 1988 







216 SunCore Reference Manual 


0.5 * scale/ scale, 0.0, 
clx, cly + scale * 0.2); 

} 

deselect_view_surface(&vsurf); 
terminate core(); 



1.2. The Factory Drawing First, here are the coordinates for the outline of the factory itself: The next set of 
Function declarations describe the outline of the windows in the factory: Now we have the 

actual code of the factory drawing function itself: The xO and yO arguments to 
the factory function describe the absolute position in world coordinates at which 
the factory should appear. The actual outline of the factory is described by the 
array of coordinates declared above. Now we draw the windows within the fac¬ 
tory: The next function is the one which draws the Sun Workstations within the 
workstation segment. 


Figure 1-3 factory. c Function 


tinclude <usercore-h> 
tinclude "factory.h" 


static float factdx[] 

static float factdy[] 

static float winddx[] 
static float winddy[] 
static int black = 3; 
static int brick = 1; 
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factory(xO, yO) 
float xO, yO; 

{ 

set_fill_index (brick) ; 

move_abs_2 (xO, yO); /* Move to appropriate position */ 
polygon__rel_2 (faetdx, faetdy, 12); /* Draw the factory outline */ 

set_fill_index (black) ; 

move_rel_2 (5.0/ 10.0); /* Move to position of first window */ 

polygon_rel_2 (winddx, winddy, 4); /* and draw the window */ 

move_rel_2(15.0/ 0.0); /* Move to position of second window */ 

polygon_rel_2 (winddx, winddy, 4); /* and draw the window */ 

set_fill_index(1); /* reset fill index */ 

} 


O 
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1.3. The Workstation The declarations below describe the outline of the Sun Workstation. Tube 

Drawing Function describes the screen, Case describes the outer outline of the case, base describes 

the base of the Workstation, and keybd describes the appearance of the keyboard: 
Then all we have to do is move to the coordinates that were supplied as function 
arguments, and draw the lines: 

Figure 1-4 sunws. c Function 


#include <usercore-h> 
tinclude "factory.h” 


static 

f l,oat 

tubex[] = {0.0, 

5.0, 

0.0, -5.0}; 


static 

float 

tubey[] = {5.0, 

0.0, 

-5.0, 0.0}; 


static 

float 

casex[] = {1.0, 

7.0, 

1.0, 1.0, -1.0, 

-7.0, -1.0}; 

static 

float 

casey[] = {7.0, 

0.0, 

-7.0, 1.0, 7.0, 

0.0, -1.0}; 

static 

float 

basex[] = {9.0, 

-1.0, 

-1.0, -5.0, -1. 

0}; 

static 

float 

basey[] = {0.0, 

0.0, 

-2.0, 0.0, 2.0}; 



static float keybdx[] = {0.0, 10.0, 3.0, 0.0, -10.0, -3.0, 10.0, 3.0); 
static float keybdy[] == {-1.0, 0.0, 2.0, 2.0, 0.0, -3.0, 0.0, 3.0); 

sunws(xO, yO) 
float xO, yO; 

{ 

inove_abs_2(xO+5.0, yO+8.0); /* Move to the position given */ 
polyline_rel_2(tubex, tubey, 4); /* Draw the tube */ 

move_rel__2 (-2.0, -1.0); 

polyline_rel_2 (casex, casey, 7); /* Draw the case */ 

move_rel_2(-1.0, -7.0); 

polyline_rel_2(basex, basey, 5); /* Draw the base */ 

move_abs_2 (xO, yO+1 - 0) ; 

polyline_rel_2(keybdx, keybdy, 8); /* Draw the keyboard */ 

} 


1.4. The Chip Drawing The declarations below describe the outline of the chips. Plasti describes the out- 

Function line of the chip itself, while lead describes the outline of the leads on the chip: 

Then all we have to do is move to the coordinates that were supplied as function 
arguments, and draw the lines: 
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Figure 1-5 chip. c Function 


#include <usercore.h> 

#include "factory.h” 

static float plastix[] = {0.0, 16.0, 0.0, -16.0}; 
static float plastiy[] = {4.0, 0.0, ^4.0, 0.0}; 

static float leadx[] = {-1.0, 2.0, -1.0, 0.0}; 
static float leady[] = {2.0, 0.0, -2.0, -4.0}; 

chip(x0, yO) 
float xO, yO; 

{ 

short i; 

set_rasterop(XORROP); 

move_abs_2(xO, yO); /* Move to appropriate position */ 
polyline__rel_2 (plastix, plastiy, 4); /* Draw the chip */ 

move_rel_2(2.0, 1.0); 

for (i=0; i<5; i++) { /* Draw the leads on the chip */ 

polyline_rel_2(leadx, leady, 4); 
move rel 2(3.0, 4.0); 


set_rasterop(NORMAL); /* Reset rasterop */ 


1.5. The Cloud Drawing 
Function 


The last function is the one that draws the cloud. The cloud function is easy: all 
we have to do is draw its outline. The actual scaling of the cloud is done in the 
main program. 

The declarations below describe the outline of the cloud; Then all we have to do 
is move to the coordinates that were supplied as function arguments, and draw 
the lines; 
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Figure 1-6 cloud. c Function 


#include <usercore.h> 
finclude "factory.h" 

static float cloudx[] 


static float cloudy[] 


cloud(xO, yO) 
float xO, yO; 

{ 

move_abs_2 (xO^ yO); 

polyline_rel_2(cloudx, cloudy/ 21); 

} 
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allocate_raster (), 66 
attributes, 73 

d5mainic, 45,46,73 

image transformation type, 85 

primitive, 73 

segment, 73 

static, 46, 73 

attributes, retained segment static, 46 
await_any_button (), 103 
await.__any__but.t.on_get._locator_2 (), 105 
await.__any_but.t.on_get._valuat:or (), 105 
await_keyboard 0, 104 
await_pick (), 103 
await__stroke_2 0, 104 


batching updates, 20 
begin_batch__of_updates (), 20 
BUTTON input device, 97 


c 

character quality constants, 11 
clipping, 25 

close_retained_seginent (), 47 
close_temporary_segment (), 49 
constants, 10 thru 13 
character quality, 11 
image transformation type, 11 
initialization, 10 
input device, 12 
line-style, 12 

polygon rendering style, 13 
RasterOp, 12 
text font selection, 12 
transform, 11 
control, 17 
drag, 21 

error handling, 17 
frame, 17 
initialization, 17 
picture change, 17 
termination, 17 
view surface, 17 
coordinate systems, 8 
normalized device, 8 


coordinate systems, continued 
world, 8 

Core type definitions, 207 thru 209 
create_retained_segment 0,47 
Greate_temporary_segment (), 49 
current position, moving, 56 

D 

data type definitions, 207 thru 209 
def ine_color__indices (), 78 
delete_all_retained_segments (),48 
delete__retained_segment (),47 
deselect_view__surf ace (), 19 
drag control, 21 
dynamic attributes 
detectabiliQr, 86 
highlighting, 86 
image transformation, 86 
visibility, 86 

E 

echoing, 98 thru 101 

BUTTON device, 99 
KEYBOARD device, 99 
LOCATOR device, 100 
PICK device, 99 
STROKE device, 99 
VALUATOR device, 100 
end_batch_of_updates (), 20 
error control, 20 
error handling, 17 
error reporting, 10 
event-generating devices, 97 

F 

f ile__to_raster (), 67 
FORTRAN interface 

function definitions, 159 thru 111 
function name mapping, 155 /Aru 159 / 

programming hints, 152 r/iTM 154 
using FORTRAN, 151 
frame control, 17 
f ree_raster 0,67 
functional capabilities 
classification, 9 
dimension levels, 10 
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functional capabilities, continued 
input, 9 
output, 9 

G 

get_mouse__st.ate (), 105 
get_raster (), 66 
get_view_surface (), 119 

I 

image transformation type attribute 
none, 46 

transformable 2D, 46 
transformable 3D, 46 
translatable 2D, 46 
translatable 3D, 46 

image transformation type constants, 11 
initialization and termination, 17 thru 18 
initialization constants, 10 
init.ialize__core (), 18 
initialize^device(), 98 
initialize_view_surface(), 19 
input device constants, 12 
input devices, 97 
BUTTON, 97 
echoing, 98 thru 101 
event generating, 97 
initializing, 98 
KEYBOARD, 97 
LOCATOR, 97 
PICK, 97 

reading, 102 thru 106 
sampled, 97 
STROKE, 97 
terminating, 98 
VALUATOR, 97 
input primitives, 97 
inquire_char just (), 84 
inquire_charpath_2 (), 84 
inquire_charpath_3 (), 84 
inquire_charprecision (), 84 
inquire__charsize (), 83 
inquire__charspace (), 84 
inquire_charup_2 (), 84 
inquire_charup_3 (), 84 
inquire_color_indices (), 82 
inc[uire_current__position__2 <), 56 
inquire__current__position_3 (), 57 
inquire_detectability 0,91 
inquire_echo (), 106 
inc[uire_echo_position (), 106 
inquire_echo_surf ace <), 106 
inquire_f ill__index (), 83 
inquire_font (), 83 
inquire__highlighting (), 91 
inquire_iinage_transformation_2 (), 91 
inquire_image_transforination_3 (),92 
inquire__image__transformation_type (), 86 
inquire_image__translate_2 (), 91 
inquire_iinage_translate_3 (), 91 


inquire_^inverse_composite_matrix (), 42 
inquire^keyboard (), 107 
inquire_line_index (), 82 
inquire^linestyle (), 83 
inquire__linewidth (), 83 
inquire_locator_2 (), 106 
inquire_jnarker_syinbol (), 85 
inquire_ndc_space_2 (), 38,40 
inquire_ndc_space__3 (), 38,40 
inquire_open_retained_segtnent () ,49 
inquire__open_temporary_segment (), 49 
inquire_j>ick_id (), 84 
inquire_polygon_edge_style (), 83 
inquire_polygon_interior_style (), 83 
inquire_primitive_attributes (), 85 
inquirej>rojaction <), 38,40 
inquire_rasterop (), 84 
inquire__retained_segment_names (), 48 
inquire__retained__segment_surfaces (), 48 
inquire_segment__detectability (), 92 
inquire__segment_highlighting (), 92 
inquire_segment^image_transformation_2 (), 92 
inquire__segment_image_transformation_3 (), 93 
inquire_segment_image_transformation_type (), 
86 

inquire_segment_image__translate_2 (), 92 
inquire_segment_image__translate__3 (), 93 
inquire__segment_visibility 0,92 
inquire__stroke (), 107 
inquire__text_extent_2 (), 59 
inquire_text_extent_3 <), 59 
inquire_^text_index {), 83 
inquire_valuator (), 106 
inquire_view_depth (), 38,40 
inquire__view_j>lane_di stance (), 38, 39 
inquire__view_jplane_normal (), 38, 39 
inquire_view_referencej>oint (), 38,39 
inquire_view_up_2 <), 38,40 
inquire_view_^up_3 (), 38,40 
inquire_viewing__control_parameters () ,42 
inquire_viewing__parameters (), 38,41 
inquire__viewport_2 (), 38,40 
inquire_viewport_3 (), 38,40 
inquire_visibility (),91 
inquire^window (), 38,40 

inquire__world_coordinate_matrix_2 (), 42 
inquire_world_coordinate_matrix_3 (), 42 

K 

KEYBOARD input device, 97 

L 

line functions, 57 
line-style constants, 12 
line_abs_2 (), 57 
1 ine__abs__3 (), 57 
line_rel_2 (), 57 
line_rei__3 (), 57 
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lint library, 8 

LOCATOR input device, 97 

M 

map_ndc_to_world_2 (), 37 
inap_ndc__to_world_3 (), 38 
inap_world_to_jndc_2 (), 38 
map_world__to__ndc__3 (), 38 
marker functions, 60 thru 61 
marker__abs_2 (),60 
inarker_abs_3 (), 60 
marker_rel_2 (>, 60 
inarker_rel__3 (), 60 
inove_abs_2 (), 56 
() f 56 

move__rel__2 {), 56 
move_rel__3 (), 56 
moving functions, 56 thru 57 

N 

NDC space, 4, 8 
new_f rame (), 20 

o 

output primitives 
line, 53 
marker, 53 
move, 53 
polygon, 53 
polyline, 53 
polymarker, 53 
rasters, 53 
text, 53 

p 

Pascal interface 

declarations, 183 thru 194 
function declarations, 185 thru 194 
function name mapping, 179 thru 183 
programming requirements, 175 thru 111 
type declarations, 183 thru 185 
using Pascal, 175 
PICK input device, 97 
picture change control, 17 
polygon functions, 63 thru 64 
polygon rendering style constants, 13 
polygon shading parameters, 61 thru 63 
polygon_abs_2 (), 64 
polygon_abs_3 (), 64 
polygon_rel_2 (), 64 
polygon_rel_3 (), 64 
polyline functions, 58 thru 59 
polyline_abs_2 (), 58 
polyline_abs_3 (), 58 
polyline_rel__2 (), 58 
polyline_rel_3 (), 58 
polyniarker_abs__2 (), 61 
polymarker_abs_3 (), 61 
polyinarker_rel_2 (>, 61 


polymarker__rel_3 (), 61 
primitive attributes, 73 
primitive static attributes 
chaijust, 75 
charpath, 75 
charprecision, 75 
charsize, 75 
charspace, 75 
champ, 75 
fiU index, 73 
font, 74 
line index, 73 
lincstyle, 73 
linewidth, 74 
marker symbol, 75 
pen, 74 
pick id, 75 

polygon edge style, 74 
polygon interior style, 74 
rasterop, 75 
text index, 73 
put_raster (), 65 

R 

raster functions, 65 thru 68 
raster_to_f ile (), 67 
RasterOp constants, 12 
rename_retained_segment (), 48 
report_most_recent_error (), 20 
restore_segment (), 50 

s 

san^led input devices, 97 
save_segment (), 49 
segment attributes, 46 thru 47,73 
detectability, 46 
highlighting, 46 
image transformation, 46 
visibility, 46 
segmentation, 45 
segments, 45 

attributes, 45,47 

d 3 mamic attributes, 45,46,47, 86 
operations, 47,49 
retained, 45 
static attributes, 46, 85 
temporary, 45 

select_view_surface (), 19 
set_back_plane_clipping (), 36 
set_char just 0,81 
set__charpath__2 (), 80 
set_charpath_3 0,81 
set_charprecision(), 81 
set_charsize 0,80 
set_charspace (), 80 
set__charup_2 {), 80 
set_charup_3 0,80 
set_coordinate_system_type (), 36 
set__detectability 0,87 
set__drag (), 21 
set^echo <), 100 
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set_echo__position (), 101 
set_echo_surface (), 101 
set_fill_index (), 79 
set_font 0,79 

set_front_plane_clipping (), 36 " 

set^highlighting (), 87 
set_image_transformation__2 (), 87 
set_image_transformation_3 (), 88 
set_image_transformation_t.ype (), 85 
set__iinage_translate_2 (), 87 
set__ima ge_t ran slat e_3 (), 88 
set_keyboard (), 102 
set_light__di recti on (), 62 
set_line_index (), 78 
set_linestyle (>, 79 
set_linewidth (), 79 
set_locator_2 (), 101 
set_marker_symbol (), 81 
set_ndc_space__2 (), 28, 31 
set_ndc_space_3 <), 28, 32 
set_output_clipping (), 36 
set_pick 0,102 
set_pick_id (), 81 
set_polygon_edge__style (), 79 
set_polygon_interior__style (), 79 
set__j)riinitive__attributes (), 82 
set__projection (), 28,30 
set_rasterop <), 81 
set_segment_detectability (), 89 
set_segment_highlighting(), 88 
set_segment__iinage_transformation__2 (), 89 
set_segment_image_transformation_3 (), 90 
set_segment_image_translate__2 (), 89 
set_segment_image_translate_3 <), 90 
set_segment_visibility (), 88 
set_shading_parameters (), 62 
set_stroke (), 102 
set_text_index (), 79 
set__valuator (), 102 
set_vertex_indices(), 63 
set__vertex_normals (), 63 
set__view_depth (), 28,33 
set_view___plane__di stance (), 28,30 
set_view_plane_normal (), 28, 30 
set_view__ref erence_point (), 28,29 
set_view__up_2 (), 28,30 
set__view_up_3 (>, 28, 31 
set_viewingj>arameters (), 28,35 
set_viewport_2 (), 28,34 
set_viewport_3 (), 28,34 
set_visibility (), 87 
set_window (), 28, 33 
set___window_clipping (), 36 
set_world_coordinate_matrix_2 (), 37 
set_world_coordinate_jnriatrix_3 (), 37 
set_zbuffer_cut (), 63 
shading 


shading, continued 
CONSTANT, 62 
GOURAUD, 62 
PHONG, 62 
shading parameters, 61 
size_raster (), 66 
static attributes, 73 
STROKE input device, 97 

T 

temporary segment, 45 
temporary segment operations, 49 
terminate__core (), 18 
terminate_device (), 98 
terminate_view__surface (), 19 
terminology, 3 thru 6 
text font selection constants, 12 
text functions, 59 thru 60 
text 0,59 
texture, 76 
black, 77 
cross hatched, 77 
grey tone, 77 
hatched left, 77 
hatched right, 77 
wallpaper, 77 
wavy lines, 77 
white, 77 

transform constants, 11 
type definitions, 207 thru 209 

u 

<usercore.h>, 10 

V 

VALUATOR input device, 97 
view surface 

bwldd, 118,152 
bw2dd, 118,152 
cgldd, 118,152 
cg2dd, 119,152 
cg4dd, 119,152 
cgpixwindd, 119,153 
control, 17 
gpldd, 119,153 
gplpixwindd, 119,153 
initializing, 18 thru 19 
pixwindd, 119,153 
selecting, 18 thru 19 
vwsurf structure, 117 
view volumes, 25 

w 

windows, 25 
world coordinates, 8 
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